@spritz-finance/service-client 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -47,6 +47,7 @@ export declare enum FeatureFlag {
47
47
  ModernTreasuryInstantPayments = "modernTreasury.instantPayments",
48
48
  ModernTreasuryMercuryFunding = "modernTreasury.mercuryFunding",
49
49
  ModernTreasuryNextDayAch = "modernTreasury.nextDayAch",
50
+ ModernTreasuryDebitCardPayouts = "modernTreasury.debitCardPayouts",
50
51
  InternalMercuryAutoTransfers = "mercury.internalAutoTransfers",
51
52
  BinanceBridgeEnabled = "binanceBridge.enabled",
52
53
  CheckbookAutomatedWires = "checkbook.automatedWires",
@@ -48,6 +48,7 @@ var FeatureFlag;
48
48
  FeatureFlag["ModernTreasuryInstantPayments"] = "modernTreasury.instantPayments";
49
49
  FeatureFlag["ModernTreasuryMercuryFunding"] = "modernTreasury.mercuryFunding";
50
50
  FeatureFlag["ModernTreasuryNextDayAch"] = "modernTreasury.nextDayAch";
51
+ FeatureFlag["ModernTreasuryDebitCardPayouts"] = "modernTreasury.debitCardPayouts";
51
52
  // Mercury
52
53
  FeatureFlag["InternalMercuryAutoTransfers"] = "mercury.internalAutoTransfers";
53
54
  // Operations
@@ -1,5 +1,5 @@
1
1
  export * as PayableAccountsClient from "./payableAccountsServiceClient";
2
- import { BankAccountPayoutRail, BankAccountUnpayableCode, ExternalBillInput, PayableAccount, PayableAccountInstitution, SimpleCardTransaction, UpsertVirtualCardInput } from "./types";
2
+ import { BankAccountPayoutRail, BankAccountUnpayableCode, DebitCardDetails, ExternalBillInput, PayableAccount, PayableAccountInstitution, SimpleCardTransaction, UpsertVirtualCardInput } from "./types";
3
3
  export declare function getAccount(accountId: string): Promise<(Omit<import("../lib/graphClient/generated").Bill, "type" | "institution"> & {
4
4
  __t: import("../lib/graphClient/generated").PayableAccountType;
5
5
  externalId?: string | null;
@@ -112,6 +112,13 @@ export declare function getAccountById(accountId: string): Promise<import("../ty
112
112
  export declare function createUSVirtualCardNoKyc(userId: string): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<PayableAccount>>;
113
113
  export declare function upsertVirtualCard(input: UpsertVirtualCardInput): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<PayableAccount>>;
114
114
  export declare function getRecentCardSpendTransactions(userId: string): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<SimpleCardTransaction[]>>;
115
+ /**
116
+ * Full debit-card document from the REST ServiceApi, including the Modern
117
+ * Treasury registration fields (`tokenizationId`, cardholder name, billing
118
+ * address) that the frozen federated graph — and therefore `getAccountById` —
119
+ * cannot expose.
120
+ */
121
+ export declare function getDebitCardById(userId: string, cardId: string): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<DebitCardDetails>>;
115
122
  /**
116
123
  * Permanently disable a payout rail for a bank account. Used when the account is
117
124
  * fine but cannot use one rail (e.g. "Transaction type not supported or
@@ -44,6 +44,7 @@ exports.getAccountById = getAccountById;
44
44
  exports.createUSVirtualCardNoKyc = createUSVirtualCardNoKyc;
45
45
  exports.upsertVirtualCard = upsertVirtualCard;
46
46
  exports.getRecentCardSpendTransactions = getRecentCardSpendTransactions;
47
+ exports.getDebitCardById = getDebitCardById;
47
48
  exports.disablePayoutRail = disablePayoutRail;
48
49
  exports.markUnpayable = markUnpayable;
49
50
  exports.PayableAccountsClient = __importStar(require("./payableAccountsServiceClient"));
@@ -102,6 +103,17 @@ async function getRecentCardSpendTransactions(userId) {
102
103
  .get(`${PAYABLE_ACCOUNTS_ENDPOINT}/virtual-card/recent-transactions/user/${userId}`)
103
104
  .then((res) => res.data);
104
105
  }
106
+ /**
107
+ * Full debit-card document from the REST ServiceApi, including the Modern
108
+ * Treasury registration fields (`tokenizationId`, cardholder name, billing
109
+ * address) that the frozen federated graph — and therefore `getAccountById` —
110
+ * cannot expose.
111
+ */
112
+ async function getDebitCardById(userId, cardId) {
113
+ return serviceClient_1.baseClient
114
+ .get(`${PAYABLE_ACCOUNTS_ROUTER_ENDPOINT}/debit-cards/${cardId}/user/${userId}`)
115
+ .then((res) => res.data);
116
+ }
105
117
  /**
106
118
  * Permanently disable a payout rail for a bank account. Used when the account is
107
119
  * fine but cannot use one rail (e.g. "Transaction type not supported or
@@ -103,6 +103,29 @@ type DebitCardModel = Omit<DebitCard, "type" | "institution"> & PayableAccountMo
103
103
  };
104
104
  type DigitalAccountModel = Omit<DigitalAccount, "type" | "institution"> & PayableAccountModelExtension;
105
105
  type OneTimePaymentModel = Omit<OneTimePayment, "type" | "institution"> & PayableAccountModelExtension;
106
+ export type DebitCardBillingAddress = {
107
+ line1: string;
108
+ line2?: string | null;
109
+ city: string;
110
+ state: string;
111
+ postalCode: string;
112
+ /** ISO 3166-1 alpha-2, e.g. "US". */
113
+ country: string;
114
+ };
115
+ /**
116
+ * Debit card as served by payable-accounts' REST ServiceApi
117
+ * (`GET /api/debit-cards/:cardId/user/:userId`). Unlike the frozen federated
118
+ * graph shape, this includes the Modern Treasury registration fields —
119
+ * `tokenizationId`, split cardholder name, billing address — decrypted from
120
+ * PPI storage. All of them must be present before a card can be paid via MT;
121
+ * legacy cards created before the Evervault flow may lack any of them.
122
+ */
123
+ export type DebitCardDetails = DebitCardModel & {
124
+ tokenizationId?: string | null;
125
+ cardholderFirstName?: string | null;
126
+ cardholderLastName?: string | null;
127
+ billingAddress?: DebitCardBillingAddress | null;
128
+ };
106
129
  export type PayableAccount = BankAcountModel | VirtualCardModel | BillModel | DebitCardModel | OneTimePaymentModel;
107
130
  export type PayableAccountOneTimePayment = OneTimePaymentModel;
108
131
  export type PayableAccountBankAccount = BankAcountModel;
@@ -1,9 +1,17 @@
1
1
  export * as PlatformClient from "./platformServiceClient";
2
- import { CreateTokenizationData, CreateTokenizationRequest, IssuePayoutData, IssuePayoutRequest, MTBalancesData, PlaidTreasuryBalancesData, RelayCheckbookCardData, RelayCheckbookCardRequest, SendPaymentData, SendPaymentRequest, TabapayBalancesResponse, TabapayFundingRequirementResponse, ValidateBillData, ValidateBillRequest } from "./types";
2
+ import { CreateTokenizationData, CreateTokenizationRequest, IssueCardPayoutData, IssueCardPayoutRequest, IssuePayoutData, IssuePayoutRequest, IntegratorUsageKey, IntegratorUsageOperation, IntegratorUsageSummary, MTBalancesData, PlaidTreasuryBalancesData, RelayCheckbookCardData, RelayCheckbookCardRequest, ReleaseIntegratorUsageRequest, ReserveIntegratorUsageRequest, SendPaymentData, SendPaymentRequest, TabapayBalancesResponse, TabapayFundingRequirementResponse, ValidateBillData, ValidateBillRequest } from "./types";
3
3
  export declare function validateBill(request: ValidateBillRequest): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<ValidateBillData>>;
4
4
  export declare function tabapayBalances(): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<TabapayBalancesResponse>>;
5
5
  export declare function tabapayFundingRequirement(currency?: string): Promise<TabapayFundingRequirementResponse>;
6
6
  export declare function issuePayout(request: IssuePayoutRequest): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<IssuePayoutData>>;
7
+ /**
8
+ * Push-to-debit payout via Modern Treasury. Platform lazily materializes the
9
+ * MT external account + Card from the Evervault tokenization on first payout,
10
+ * then reserves the payment order through the same funding queue as
11
+ * `issuePayout` — so `payment_order_id` is absent while the payout is queued
12
+ * and arrives later via the status outbox.
13
+ */
14
+ export declare function issueCardPayout(request: IssueCardPayoutRequest): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<IssueCardPayoutData>>;
7
15
  export declare function sendPayment(request: SendPaymentRequest): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<SendPaymentData>>;
8
16
  export declare function modernTreasuryBalances(): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<MTBalancesData>>;
9
17
  /**
@@ -25,3 +33,7 @@ export declare function relayCheckbookCard(request: RelayCheckbookCardRequest):
25
33
  * so no raw PAN reaches platform.
26
34
  */
27
35
  export declare function createTokenization(request: CreateTokenizationRequest): Promise<import("../types").ApiFailure | import("../types").ApiSuccess<CreateTokenizationData>>;
36
+ export declare function reserveIntegratorUsage(request: ReserveIntegratorUsageRequest): Promise<IntegratorUsageOperation>;
37
+ export declare function commitIntegratorUsage(key: IntegratorUsageKey): Promise<IntegratorUsageOperation>;
38
+ export declare function releaseIntegratorUsage(request: ReleaseIntegratorUsageRequest): Promise<IntegratorUsageOperation>;
39
+ export declare function getIntegratorUsage(integratorId: string): Promise<IntegratorUsageSummary>;
@@ -41,11 +41,16 @@ exports.validateBill = validateBill;
41
41
  exports.tabapayBalances = tabapayBalances;
42
42
  exports.tabapayFundingRequirement = tabapayFundingRequirement;
43
43
  exports.issuePayout = issuePayout;
44
+ exports.issueCardPayout = issueCardPayout;
44
45
  exports.sendPayment = sendPayment;
45
46
  exports.modernTreasuryBalances = modernTreasuryBalances;
46
47
  exports.plaidTreasuryBalances = plaidTreasuryBalances;
47
48
  exports.relayCheckbookCard = relayCheckbookCard;
48
49
  exports.createTokenization = createTokenization;
50
+ exports.reserveIntegratorUsage = reserveIntegratorUsage;
51
+ exports.commitIntegratorUsage = commitIntegratorUsage;
52
+ exports.releaseIntegratorUsage = releaseIntegratorUsage;
53
+ exports.getIntegratorUsage = getIntegratorUsage;
49
54
  exports.PlatformClient = __importStar(require("./platformServiceClient"));
50
55
  const axios_1 = __importDefault(require("axios"));
51
56
  // @ts-expect-error no type declarations for axios-token-interceptor
@@ -86,6 +91,18 @@ async function issuePayout(request) {
86
91
  .post(`${MT_ENDPOINT}/issue-payout`, request)
87
92
  .then((res) => res.data);
88
93
  }
94
+ /**
95
+ * Push-to-debit payout via Modern Treasury. Platform lazily materializes the
96
+ * MT external account + Card from the Evervault tokenization on first payout,
97
+ * then reserves the payment order through the same funding queue as
98
+ * `issuePayout` — so `payment_order_id` is absent while the payout is queued
99
+ * and arrives later via the status outbox.
100
+ */
101
+ async function issueCardPayout(request) {
102
+ return platformClient
103
+ .post(`${MT_ENDPOINT}/issue-card-payout`, request)
104
+ .then((res) => res.data);
105
+ }
89
106
  async function sendPayment(request) {
90
107
  return platformClient
91
108
  .post(`${MT_ENDPOINT}/send-payment`, request)
@@ -130,3 +147,28 @@ async function createTokenization(request) {
130
147
  .post(TOKENIZATIONS_ENDPOINT, request)
131
148
  .then((res) => res.data);
132
149
  }
150
+ const INTEGRATOR_USAGE_ENDPOINT = "/v1/integrator-usage";
151
+ async function reserveIntegratorUsage(request) {
152
+ return platformClient
153
+ .post(`${INTEGRATOR_USAGE_ENDPOINT}/reservations`, request)
154
+ .then((res) => res.data);
155
+ }
156
+ async function commitIntegratorUsage(key) {
157
+ const sourceSystem = encodeURIComponent(key.sourceSystem);
158
+ const operationId = encodeURIComponent(key.operationId);
159
+ return platformClient
160
+ .post(`${INTEGRATOR_USAGE_ENDPOINT}/reservations/${sourceSystem}/${operationId}/commit`, { integratorId: key.integratorId })
161
+ .then((res) => res.data);
162
+ }
163
+ async function releaseIntegratorUsage(request) {
164
+ const sourceSystem = encodeURIComponent(request.sourceSystem);
165
+ const operationId = encodeURIComponent(request.operationId);
166
+ return platformClient
167
+ .post(`${INTEGRATOR_USAGE_ENDPOINT}/reservations/${sourceSystem}/${operationId}/release`, { integratorId: request.integratorId, reason: request.reason })
168
+ .then((res) => res.data);
169
+ }
170
+ async function getIntegratorUsage(integratorId) {
171
+ return platformClient
172
+ .get(`${INTEGRATOR_USAGE_ENDPOINT}/integrators/${encodeURIComponent(integratorId)}`)
173
+ .then((res) => res.data);
174
+ }
@@ -71,6 +71,50 @@ export interface IssuePayoutData {
71
71
  currency: "USD";
72
72
  external_id: string;
73
73
  }
74
+ export interface CardBillingAddress {
75
+ line1: string;
76
+ line2?: string;
77
+ city: string;
78
+ state: string;
79
+ postalCode: string;
80
+ /** ISO 3166-1 alpha-2, e.g. "US". */
81
+ country: string;
82
+ }
83
+ /**
84
+ * Mirrors platform's `IssueCardPayoutRequestSchema` (internal-api
85
+ * `services/modern-treasury/card-payout.ts`). Cardholder name and billing
86
+ * address must come from the caller: payable-accounts persists them
87
+ * PPI-encrypted and platform cannot reconstruct them. USD/US only — no
88
+ * currency field, by design. Takes no rail: the endpoint is push-to-card.
89
+ */
90
+ export interface IssueCardPayoutRequest {
91
+ userId: string;
92
+ /** The liabilities payment id — the idempotency anchor for the whole flow. */
93
+ debitId: string;
94
+ /** The payable-accounts debit card id. */
95
+ cardId: string;
96
+ /** Holds the `ev:` PAN token the relay decrypts on the way to MT. */
97
+ tokenizationId: string;
98
+ cardholderFirstName: string;
99
+ cardholderLastName: string;
100
+ billingAddress: CardBillingAddress;
101
+ cardNetwork?: string;
102
+ cardLastFour?: string;
103
+ recipientEmail?: string;
104
+ amount: number;
105
+ metadata?: Record<string, string>;
106
+ statementDescriptor?: string;
107
+ }
108
+ export interface IssueCardPayoutData {
109
+ /** Absent while the payout is queued for funding (`pending:*` internally). */
110
+ payment_order_id?: string;
111
+ status: string;
112
+ type: string;
113
+ direction: "credit";
114
+ amount: number;
115
+ currency: "USD";
116
+ external_id: string;
117
+ }
74
118
  export interface SendPaymentRequest {
75
119
  destination: "checkbook" | "mercury";
76
120
  amount: number;
@@ -164,3 +208,70 @@ export interface CreateTokenizationData {
164
208
  type: string;
165
209
  created_at: string;
166
210
  }
211
+ export type IntegratorUsageOperation = {
212
+ id: string;
213
+ integratorId: string;
214
+ sourceSystem: string;
215
+ operationId: string;
216
+ rail: string;
217
+ state: "reserved" | "committed" | "released";
218
+ sourceCurrency: string;
219
+ transactionPrincipalMinor: string;
220
+ lockedUsdPrincipal: string;
221
+ tier: string;
222
+ phase: string;
223
+ policyVersion: string;
224
+ reservationExpiresAt: string | null;
225
+ committedAt: string | null;
226
+ releasedAt: string | null;
227
+ releaseReason: string | null;
228
+ createdAt: string;
229
+ updatedAt: string;
230
+ };
231
+ export type ReserveIntegratorUsageRequest = {
232
+ integratorId: string;
233
+ sourceSystem: string;
234
+ operationId: string;
235
+ rail: string;
236
+ transactionPrincipalMinor: string;
237
+ sourceCurrency: string;
238
+ lockedUsdPrincipalCents: string;
239
+ reservationExpiresAt?: string;
240
+ };
241
+ export type IntegratorUsageKey = {
242
+ integratorId: string;
243
+ sourceSystem: string;
244
+ operationId: string;
245
+ };
246
+ export type ReleaseIntegratorUsageRequest = IntegratorUsageKey & {
247
+ reason: string;
248
+ };
249
+ export type IntegratorUsageSummary = {
250
+ integratorId: string;
251
+ policy: {
252
+ tier: string;
253
+ phase: string;
254
+ policyVersion: string;
255
+ liveMoneyAllowed: boolean;
256
+ liveMoneyBlockReason?: string;
257
+ planAdjustmentBps: number;
258
+ monthlyMinimumUsd: string;
259
+ developerLimits?: {
260
+ perTransactionUsd: string;
261
+ lifetimeTransactionCount: number;
262
+ lifetimeVolumeUsd: string;
263
+ };
264
+ launchStartedAt?: string;
265
+ launchEndsAt?: string;
266
+ decisionRequiredAt?: string;
267
+ };
268
+ committedTransactionCount: number;
269
+ committedVolumeUsd: string;
270
+ reservedTransactionCount: number;
271
+ reservedVolumeUsd: string;
272
+ currentMonthKey: string;
273
+ currentMonthCommittedCount: number;
274
+ currentMonthCommittedVolumeUsd: string;
275
+ remainingTransactionCount?: number;
276
+ remainingVolumeUsd?: string;
277
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spritz-finance/service-client",
3
- "version": "0.18.0",
3
+ "version": "0.20.0",
4
4
  "gitHead": "06f8e96b7b38c34df26a38da329331940675e4f8",
5
5
  "description": "Service client",
6
6
  "license": "ISC",