Add automatic pix

CHANGELOG.md

@@ -13,6 +13,9 @@ Given a version number MAJOR.MINOR.PATCH, increment:
 
 
 ## [Unreleased]
+### Added
+- PixPullSubscription resource
+- PixPullRequest resource
 
 ## [0.18.0] - 2026-05-04
 ### Added

README.md

@@ -54,6 +54,8 @@ This SDK version is compatible with the Stark Infra API v2.
         - [DynamicBrcode](#create-dynamicbrcodes): Create dynamic Pix BR codes
         - [BrcodePreview](#create-brcodepreviews): Read data from BR Codes before
         - [PixDispute](#create-pixdisputes): Create PixDisputes
+        - [PixPullSubscription](#create-pixpullsubscriptions): Set up recurring Pix debit authorizations
+        - [PixPullRequest](#create-pixpullrequests): Trigger automatic Pix debits against a subscription
     - [Lending](#lending)
         - [CreditNote](#create-creditnotes): Create credit notes
         - [CreditPreview](#create-creditpreviews): Create credit previews
@@ -2543,6 +2545,271 @@ const starkinfra = require('starkinfra');
 })();
 ```
 
+### Create PixPullSubscriptions
+
+You can create recurring Pix debit authorizations to allow a receiver to pull a series of Pix payments from a sender.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscriptions = await starkinfra.pixPullSubscription.create([
+        new starkinfra.PixPullSubscription({
+            bacenId: 'RR2017032900000000000000003',
+            externalId: 'my-subscription-001',
+            installmentStart: '2026-04-01T12:00:00+00:00',
+            interval: 'month',
+            receiverName: 'Edward Stark',
+            receiverTaxId: '20.018.183/0001-80',
+            senderAccountNumber: '876543-2',
+            senderBankCode: '20018183',
+            senderBranchCode: '1357-9',
+            senderTaxId: '01234567890',
+            type: 'push',
+            amount: 11234,
+            description: 'Monthly subscription',
+            tags: ['employees', 'monthly'],
+        }),
+    ]);
+
+    for (let subscription of subscriptions) {
+        console.log(subscription);
+    }
+})();
+```
+
+### Query PixPullSubscriptions
+
+You can query multiple PixPullSubscriptions according to filters.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscriptions = await starkinfra.pixPullSubscription.query({
+        limit: 10,
+        after: '2026-01-01',
+        before: '2026-04-30',
+        status: ['active'],
+        tags: ['monthly'],
+    });
+
+    for await (let subscription of subscriptions) {
+        console.log(subscription);
+    }
+})();
+```
+
+### Get a PixPullSubscription
+
+After its creation, information on a PixPullSubscription may be retrieved by its id.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscription = await starkinfra.pixPullSubscription.get('5656565656565656');
+    console.log(subscription);
+})();
+```
+
+### Update a PixPullSubscription
+
+You can update a PixPullSubscription by passing its id. When patching `status` to `"confirmed"`, `senderCityCode` MUST be present.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscription = await starkinfra.pixPullSubscription.update(
+        '5656565656565656',
+        {status: 'confirmed', senderCityCode: '3550308'}
+    );
+    console.log(subscription);
+})();
+```
+
+### Cancel a PixPullSubscription
+
+Cancel a specific PixPullSubscription using its id and a reason. The reason is sent as a query parameter on the DELETE request.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscription = await starkinfra.pixPullSubscription.cancel(
+        '5656565656565656',
+        'accountClosed'
+    );
+    console.log(subscription);
+})();
+```
+
+### Query PixPullSubscription logs
+
+You can query PixPullSubscription logs to better understand PixPullSubscription life cycles.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let logs = await starkinfra.pixPullSubscription.log.query({
+        limit: 50,
+        after: '2026-01-01',
+        before: '2026-04-30',
+        subscriptionIds: ['5656565656565656'],
+    });
+
+    for await (let log of logs) {
+        console.log(log);
+    }
+})();
+```
+
+### Get a PixPullSubscription log
+
+You can also get a specific log by its id.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let log = await starkinfra.pixPullSubscription.log.get('5155165527080960');
+    console.log(log);
+})();
+```
+
+### Process inbound PixPullSubscription events
+
+Inbound PixPullSubscription events will be POSTed at your registered endpoint. You can use the `parse` function to verify the digital signature and reconstruct the PixPullSubscription object.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let subscription = await starkinfra.pixPullSubscription.parse(
+        '{"bacenId": "RR2017032900000000000000003", ...}',
+        'MEUCIQC7FVhXdripx/aXg5yNLxmNoZlehpyvX3QYDXJ8o3PAZQIgVe1omKFh7Vd54ML4U1z7L+kpx+GHl+G2XLeFTLZeBJk='
+    );
+    console.log(subscription);
+})();
+```
+
+### Create PixPullRequests
+
+You can create PixPullRequests to trigger automatic debits against an active PixPullSubscription.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let requests = await starkinfra.pixPullRequest.create([
+        new starkinfra.PixPullRequest({
+            amount: 11234,
+            due: '2026-04-15T12:00:00+00:00',
+            endToEndId: 'E00002649202201172211u34srod19le',
+            receiverAccountNumber: '876543-2',
+            receiverAccountType: 'checking',
+            receiverBankCode: '20018183',
+            reconciliationId: 'cycle-202604',
+            subscriptionId: '5656565656565656',
+            tags: ['monthly'],
+        }),
+    ]);
+
+    for (let request of requests) {
+        console.log(request);
+    }
+})();
+```
+
+### Query PixPullRequests
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let requests = await starkinfra.pixPullRequest.query({
+        limit: 10,
+        status: ['created', 'active'],
+        subscriptionIds: ['5656565656565656'],
+    });
+
+    for await (let request of requests) {
+        console.log(request);
+    }
+})();
+```
+
+### Get a PixPullRequest
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let request = await starkinfra.pixPullRequest.get('5656565656565656');
+    console.log(request);
+})();
+```
+
+### Update a PixPullRequest
+
+Change status to `"scheduled"` or `"denied"`. When denying, `reason` is required.
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let request = await starkinfra.pixPullRequest.update(
+        '5656565656565656',
+        {status: 'denied', reason: 'senderAccountClosed'}
+    );
+    console.log(request);
+})();
+```
+
+### Cancel a PixPullRequest
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let request = await starkinfra.pixPullRequest.cancel(
+        '5656565656565656',
+        'senderUserRequested'
+    );
+    console.log(request);
+})();
+```
+
+### Query PixPullRequest logs
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let logs = await starkinfra.pixPullRequest.log.query({
+        limit: 50,
+        requestIds: ['5656565656565656'],
+    });
+
+    for await (let log of logs) {
+        console.log(log);
+    }
+})();
+```
+
+### Get a PixPullRequest log
+
+```javascript
+const starkinfra = require('starkinfra');
+
+(async() => {
+    let log = await starkinfra.pixPullRequest.log.get('5155165527080960');
+    console.log(log);
+})();
+```
+
 ## Lending
 If you want to establish a lending operation, you can use Stark Infra to
 create a CCB contract. This will enable your business to lend money without

index.js

@@ -23,6 +23,8 @@ exports.pixDispute = require('./sdk/pixDispute');
 exports.pixReversal = require('./sdk/pixReversal');
 exports.pixStatement = require('./sdk/pixStatement');
 exports.pixUser = require('./sdk/pixUser');
+exports.pixPullSubscription = require('./sdk/pixPullSubscription');
+exports.pixPullRequest = require('./sdk/pixPullRequest');
 exports.pixInfraction = require('./sdk/pixInfraction');
 exports.pixChargeback = require('./sdk/pixChargeback');
 exports.pixDomain = require('./sdk/pixDomain');
@@ -80,6 +82,8 @@ exports.PixReversal = exports.pixReversal.PixReversal;
 exports.PixStatement = exports.pixStatement.PixStatement;
 exports.PixUser = exports.pixUser.PixUser;
 exports.PixInfraction = exports.pixInfraction.PixInfraction;
+exports.PixPullSubscription = exports.pixPullSubscription.PixPullSubscription;
+exports.PixPullRequest = exports.pixPullRequest.PixPullRequest;
 exports.PixChargeback = exports.pixChargeback.PixChargeback;
 exports.PixDomain = exports.pixDomain.PixDomain;
 exports.DynamicBrcode = exports.dynamicBrcode.DynamicBrcode;

sdk/pixPullRequest/index.js

@@ -0,0 +1,10 @@
+const pixPullRequest = require('./pixPullRequest.js');
+
+exports.log = require('./log');
+exports.create = pixPullRequest.create;
+exports.query = pixPullRequest.query;
+exports.get = pixPullRequest.get;
+exports.page = pixPullRequest.page;
+exports.update = pixPullRequest.update;
+exports.cancel = pixPullRequest.cancel;
+exports.PixPullRequest = pixPullRequest.PixPullRequest;

sdk/pixPullRequest/log/index.js

@@ -0,0 +1,5 @@
+const log = require('./log.js');
+
+exports.get = log.get;
+exports.query = log.query;
+exports.page = log.page;

sdk/pixPullRequest/log/log.js

@@ -0,0 +1,58 @@
+const rest = require('../../utils/rest.js');
+const check = require('starkcore').check;
+const Resource = require('../../utils/resource.js').Resource;
+const { PixPullRequest } = require('../pixPullRequest.js');
+
+
+class Log extends Resource {
+    /**
+     * PixPullRequest Log object
+     *
+     * @param id [string]
+     * @param created [string]
+     * @param type [string]
+     * @param errors [list of strings]
+     * @param request [PixPullRequest]
+     */
+    constructor({
+                    id = null, created = null, type = null, errors = null, request = null
+                }) {
+        super(id);
+
+        this.created = check.datetime(created);
+        this.type = type;
+        this.errors = errors;
+        this.request = request ? Object.assign(new PixPullRequest(request), request) : request;
+    }
+}
+
+exports.Log = Log;
+let resource = {'class': exports.Log, 'name': 'PixPullRequestLog'};
+
+
+exports.get = async function (id, {user} = {}) {
+    return rest.getId(resource, id, user);
+};
+
+exports.query = async function ({limit, after, before, types, requestIds, user} = {}) {
+    let query = {
+        limit: limit,
+        after: after,
+        before: before,
+        types: types,
+        requestIds: requestIds,
+    };
+    return rest.getList(resource, query, user);
+};
+
+exports.page = async function ({cursor, limit, after, before, types, requestIds, user} = {}) {
+    let query = {
+        cursor: cursor,
+        limit: limit,
+        after: after,
+        before: before,
+        types: types,
+        requestIds: requestIds,
+    };
+    return rest.getPage(resource, query, user);
+};