diff --git a/.gitignore b/.gitignore index c85fe68..9487e48 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,4 @@ dist-deno /*.tgz .idea/ .eslintcache - +oidc diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 71e95ba..d353515 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.20.0" + ".": "0.21.0" } diff --git a/.stats.yml b/.stats.yml index d469da0..7e70f72 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 23 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/fragment-foundries-inc-dash%2Ffragment-1ac1d5e34a8fbabcecc040255a4c5f3d9e6e986bb1b57ec76ed8cd146e5e2bf4.yml -openapi_spec_hash: ec746b4b585a33e6f5f722537e37c956 -config_hash: afc05056f5a776aa1501387e38c4820e +configured_endpoints: 22 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/fragment-foundries-inc-dash%2Ffragment-8472a9bd15eaa5b8aa9c12513d02b06ae385d06dd48e94a23f121678981de98a.yml +openapi_spec_hash: 4c42faa5ab6443bab546568adc330b7a +config_hash: 8e4b2d3ac55a0b2cdecfba99a1925e6f diff --git a/CHANGELOG.md b/CHANGELOG.md index d7370e7..6b5318c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,30 @@ # Changelog +## 0.21.0 (2026-04-13) + +Full Changelog: [v0.20.0...v0.21.0](https://github.com/fragment-dev/fragment-typescript/compare/v0.20.0...v0.21.0) + +### Features + +* **api:** update SDK from prod (511af1bcd4001be60c589fed1d05a5814e416679) ([484943a](https://github.com/fragment-dev/fragment-typescript/commit/484943a2f97b25aa4949d112a892884a03f28534)) +* **api:** update SDK from prod (523b1fdd6cc6b5732ccdad5095c21f69fe1f7489) ([91ee3b5](https://github.com/fragment-dev/fragment-typescript/commit/91ee3b5837e439946ba9c2a4beff1b6e44c7bca0)) +* **api:** update SDK from prod (729db28098a20ebc22e879a2cd1c6ad860f9ce4c) ([99ffd26](https://github.com/fragment-dev/fragment-typescript/commit/99ffd26009fa316ca340db2e8e83155a970b2c62)) +* **api:** update SDK from prod (8051461980fb65468797d0b82dfa42dee9014004) ([79a14d1](https://github.com/fragment-dev/fragment-typescript/commit/79a14d16c8774e9226d928a7634d1c26cf2044b0)) +* **api:** update SDK from prod (a5eb093078fe5947a299bccafd30a0c7f2e90790) ([a6843ba](https://github.com/fragment-dev/fragment-typescript/commit/a6843ba30ed876c02ace9e0746986ee1ce0c6e93)) +* **api:** update SDK from prod (b3080493fb6bb118abdd03644b9ef6f59d417a3c) ([b0123c3](https://github.com/fragment-dev/fragment-typescript/commit/b0123c3ca8e5b901d945eca65808ff5948bb357b)) +* **api:** update SDK from prod (b8f6f1940acd3d10fc17aaeb59cd75281f3c6436) ([68cebf4](https://github.com/fragment-dev/fragment-typescript/commit/68cebf44aacd4feba688a21d83d1848aa4a1e684)) +* **api:** update SDK from prod (e1ebb9e4d62034855202a8ff99690880c072d953) ([aeff356](https://github.com/fragment-dev/fragment-typescript/commit/aeff3566c323f4bb81fc93ea3c9c9812b493d4a1)) + + +### Bug Fixes + +* **internal:** gitignore generated `oidc` dir ([b489349](https://github.com/fragment-dev/fragment-typescript/commit/b4893492a7003c791297067170805d88e1a08a72)) + + +### Chores + +* **internal:** codegen related update ([558e630](https://github.com/fragment-dev/fragment-typescript/commit/558e630e873639730aa5c1a967ada782791378d5)) + ## 0.20.0 (2026-03-27) Full Changelog: [v0.19.0...v0.20.0](https://github.com/fragment-dev/fragment-typescript/compare/v0.19.0...v0.20.0) diff --git a/api.md b/api.md index c607b14..d6a3daa 100644 --- a/api.md +++ b/api.md @@ -69,7 +69,6 @@ Types: - TransactionRetrieveResponse - TransactionUpdateResponse - TransactionListResponse -- TransactionCreateAllocationsResponse - TransactionListHistoryResponse - TransactionSearchResponse - TransactionSearchAllocationsResponse @@ -80,7 +79,6 @@ Methods: - client.transactions.retrieve(transactionRef) -> TransactionRetrieveResponse - client.transactions.update(transactionRef, { ...params }) -> TransactionUpdateResponse - client.transactions.list({ ...params }) -> TransactionListResponse -- client.transactions.createAllocations(transactionRef, { ...params }) -> TransactionCreateAllocationsResponse - client.transactions.listHistory(transactionRef) -> TransactionListHistoryResponse - client.transactions.search({ ...params }) -> TransactionSearchResponse - client.transactions.searchAllocations({ ...params }) -> TransactionSearchAllocationsResponse diff --git a/package.json b/package.json index 741ecba..a99da10 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@fragment-dev/ts-node", - "version": "0.20.0", + "version": "0.21.0", "description": "The official TypeScript library for the Fragment API", "author": "Fragment <>", "types": "dist/index.d.ts", diff --git a/src/client.ts b/src/client.ts index 5892552..d6a6bbe 100644 --- a/src/client.ts +++ b/src/client.ts @@ -48,8 +48,6 @@ import { import { Role, RoleCreateParams, RoleCreateResponse, RoleListResponse, Roles } from './resources/roles'; import { Transaction, - TransactionCreateAllocationsParams, - TransactionCreateAllocationsResponse, TransactionCreateParams, TransactionCreateResponse, TransactionListHistoryResponse, @@ -843,6 +841,9 @@ export class Fragment { static toFile = Uploads.toFile; + /** + * External account management operations + */ externalAccounts: API.ExternalAccounts = new API.ExternalAccounts(this); /** * Invoice management operations @@ -860,6 +861,9 @@ export class Fragment { * Transaction sync operations */ transactions: API.Transactions = new API.Transactions(this); + /** + * User management operations + */ users: API.Users = new API.Users(this); } @@ -919,14 +923,12 @@ export declare namespace Fragment { type TransactionRetrieveResponse as TransactionRetrieveResponse, type TransactionUpdateResponse as TransactionUpdateResponse, type TransactionListResponse as TransactionListResponse, - type TransactionCreateAllocationsResponse as TransactionCreateAllocationsResponse, type TransactionListHistoryResponse as TransactionListHistoryResponse, type TransactionSearchResponse as TransactionSearchResponse, type TransactionSearchAllocationsResponse as TransactionSearchAllocationsResponse, type TransactionCreateParams as TransactionCreateParams, type TransactionUpdateParams as TransactionUpdateParams, type TransactionListParams as TransactionListParams, - type TransactionCreateAllocationsParams as TransactionCreateAllocationsParams, type TransactionSearchParams as TransactionSearchParams, type TransactionSearchAllocationsParams as TransactionSearchAllocationsParams, }; diff --git a/src/internal/utils/env.ts b/src/internal/utils/env.ts index 2d84800..cc5fa0f 100644 --- a/src/internal/utils/env.ts +++ b/src/internal/utils/env.ts @@ -9,10 +9,10 @@ */ export const readEnv = (env: string): string | undefined => { if (typeof (globalThis as any).process !== 'undefined') { - return (globalThis as any).process.env?.[env]?.trim() ?? undefined; + return (globalThis as any).process.env?.[env]?.trim() || undefined; } if (typeof (globalThis as any).Deno !== 'undefined') { - return (globalThis as any).Deno.env?.get?.(env)?.trim(); + return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined; } return undefined; }; diff --git a/src/resources/external-accounts.ts b/src/resources/external-accounts.ts index cd25721..81781e3 100644 --- a/src/resources/external-accounts.ts +++ b/src/resources/external-accounts.ts @@ -4,9 +4,12 @@ import { APIResource } from '../core/resource'; import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; +/** + * External account management operations + */ export class ExternalAccounts extends APIResource { /** - * Creates a new external account + * Creates an external account. * * @example * ```ts @@ -25,7 +28,7 @@ export class ExternalAccounts extends APIResource { } /** - * Lists all external accounts for the workspace + * Lists all external accounts. * * @example * ```ts @@ -39,34 +42,34 @@ export class ExternalAccounts extends APIResource { } /** - * External account object + * External account object. */ export interface ExternalAccount { /** - * Fragment-generated unique ID for the external account + * FRAGMENT generated unique ID. */ id: string; /** - * User-provided external ID + * User-provided unique ID. */ external_id: string; /** - * Human-readable name for the external account + * Name of the account. */ name: string; } export interface ExternalAccountCreateResponse { /** - * External account object + * External account object. */ data: ExternalAccount; } /** - * List of external accounts + * List of external accounts. */ export interface ExternalAccountListResponse { data: Array; @@ -74,12 +77,12 @@ export interface ExternalAccountListResponse { export interface ExternalAccountCreateParams { /** - * External ID for the account (user-provided, unique, mutable) + * User-provided unique ID. */ external_id: string; /** - * Human-readable name for the external account (mutable) + * Name of the account. */ name: string; } diff --git a/src/resources/index.ts b/src/resources/index.ts index 504d4b1..0c7be81 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -42,14 +42,12 @@ export { type TransactionRetrieveResponse, type TransactionUpdateResponse, type TransactionListResponse, - type TransactionCreateAllocationsResponse, type TransactionListHistoryResponse, type TransactionSearchResponse, type TransactionSearchAllocationsResponse, type TransactionCreateParams, type TransactionUpdateParams, type TransactionListParams, - type TransactionCreateAllocationsParams, type TransactionSearchParams, type TransactionSearchAllocationsParams, } from './transactions'; diff --git a/src/resources/invoices.ts b/src/resources/invoices.ts index 4d67376..b3b6ce9 100644 --- a/src/resources/invoices.ts +++ b/src/resources/invoices.ts @@ -11,7 +11,7 @@ import { path } from '../internal/utils/path'; */ export class Invoices extends APIResource { /** - * Creates a new invoice + * Creates an invoice. * * @example * ```ts @@ -33,7 +33,7 @@ export class Invoices extends APIResource { } /** - * Gets an invoice by ID with balance details + * Retrieves an invoice. * * @example * ```ts @@ -47,7 +47,7 @@ export class Invoices extends APIResource { } /** - * Updates an invoice + * Updates an invoice. * * @example * ```ts @@ -62,7 +62,7 @@ export class Invoices extends APIResource { } /** - * Lists all invoices for the workspace + * Lists all invoices. * * @example * ```ts @@ -74,7 +74,7 @@ export class Invoices extends APIResource { } /** - * Gets the version history of an invoice + * Retrieves the version history of an invoice. * * @example * ```ts @@ -88,13 +88,12 @@ export class Invoices extends APIResource { } /** - * Searches invoices + * Searches invoices. * * @example * ```ts * const response = await client.invoices.search({ * filter: {}, - * page_info: {}, * }); * ``` */ @@ -104,84 +103,83 @@ export class Invoices extends APIResource { } /** - * Invoice object + * Invoice object. */ export interface Invoice { /** - * Unique identifier for the invoice + * Unique invoice ID. */ id: string; /** - * ISO 8601 timestamp when the invoice was created + * Timestamp when the invoice was created. Uses ISO 8601 format. */ created: string; /** - * @deprecated Deprecated: The status of the invoice + * @deprecated Status of the invoice. Deprecated. */ status: 'active'; /** - * Metadata tags for this invoice + * Tags for the invoice. */ tags: Array; /** - * The current version of the invoice. Pass this value when updating to ensure - * thread safety. + * Current version of the invoice. */ version: number; /** - * Workspace ID this invoice belongs to + * Workspace the invoice belongs to. */ workspace_id: string; /** - * List of line items associated with this invoice + * Line items for the invoice. */ line_items?: Array; /** - * ISO 8601 timestamp when the invoice was last modified + * Timestamp when the invoice was last modified. Uses ISO 8601 format. */ modified?: string; } export namespace Invoice { /** - * A key-value tag pair + * A key-value tag pair. */ export interface Tag { /** - * Tag key + * Tag key. */ key: string; /** - * Tag value + * Tag value. */ value: string; } /** - * Invoice line item object + * Invoice line item. */ export interface LineItem { /** - * Unique identifier for the line item + * FRAGMENT generated unique ID. */ id: string; /** - * @deprecated Deprecated: use price.amount instead. Total amount in smallest - * currency unit (represented as string for bigint) + * @deprecated Total amount as a string in the smallest currency unit, such as + * cents for USD. Deprecated, use price.amount instead. */ amount: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency_code: | 'ADA' @@ -365,68 +363,68 @@ export namespace Invoice { | 'CUSTOM'; /** - * Description of the line item + * Description of the line item. */ description: string; /** - * Price breakdown containing amount, unit price, and quantity + * Price breakdown. */ price: LineItem.Price; /** - * ID of the product/catalog item + * Unique identifier for the product. */ product_id: string; /** - * Metadata tags for this line item + * Tags for the line item. */ tags: Array; /** - * The type of the line item + * Type of the line item. */ type: 'payin' | 'payout'; /** - * External ID of the user associated with this line item + * User-provided unique external ID. */ user_id: string; } export namespace LineItem { /** - * Price breakdown containing amount, unit price, and quantity + * Price breakdown. */ export interface Price { /** - * Total amount in smallest currency unit (represented as string for bigint) + * Total amount as a string in the smallest currency unit, such as cents for USD. */ amount: string; /** - * Quantity of units for this line item + * Number of units. */ quantity: number; /** - * Unit price in smallest currency unit (represented as string for bigint) + * Unit price as a string in the smallest currency unit, such as cents for USD. */ unit_price: string; } /** - * A key-value tag pair + * A key-value tag pair. */ export interface Tag { /** - * Tag key + * Tag key. */ key: string; /** - * Tag value + * Tag value. */ value: string; } @@ -435,35 +433,35 @@ export namespace Invoice { export interface InvoiceCreateResponse { /** - * Invoice object + * Invoice object. */ data: Invoice; } export interface InvoiceRetrieveResponse { /** - * Invoice with balance details + * Invoice with balance details. */ data: InvoiceRetrieveResponse.Data; } export namespace InvoiceRetrieveResponse { /** - * Invoice with balance details + * Invoice with balance details. */ export interface Data extends InvoicesAPI.Invoice { /** - * Invoice-level balances by currency: payins, payouts, and net (payins - payouts) + * Invoice-level balances by currency. */ balances: Array; /** - * Transaction allocations (payments) associated with this invoice. + * Payments allocated to the invoice. */ payments: Array; /** - * Users/parties involved in the invoice + * Users involved in the invoice. */ users: Array; } @@ -471,81 +469,106 @@ export namespace InvoiceRetrieveResponse { export namespace Data { export interface Balance { /** - * Currency code + * ISO 4217 or crypto currency code. */ currency: string; + /** + * Net balance breakdown. + */ net: Balance.Net; + /** + * Payins balance breakdown. + */ payins: Balance.Payins; + /** + * Payouts balance breakdown. + */ payouts: Balance.Payouts; } export namespace Balance { + /** + * Net balance breakdown. + */ export interface Net { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payins balance breakdown. + */ export interface Payins { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payouts balance breakdown. + */ export interface Payouts { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } } /** - * A payment allocated to this invoice. + * A payment allocated to the invoice. */ export interface Payment { /** - * Amount allocated in smallest currency unit as stringified bigint. + * Amount allocated as a string in the smallest currency unit, such as cents for + * USD. */ amount: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency: | 'ADA' @@ -669,910 +692,289 @@ export namespace InvoiceRetrieveResponse { | 'NGN' | 'NIO' | 'NOK' - | 'NPR' - | 'NZD' - | 'OMR' - | 'PAB' - | 'PEN' - | 'PGK' - | 'PHP' - | 'PKR' - | 'PLN' - | 'PYG' - | 'QAR' - | 'RON' - | 'RSD' - | 'RUB' - | 'RWF' - | 'SAR' - | 'SBD' - | 'SCR' - | 'SDG' - | 'SEK' - | 'SGD' - | 'SHP' - | 'SLL' - | 'SOS' - | 'SPL' - | 'SRD' - | 'SVC' - | 'SYP' - | 'STN' - | 'SZL' - | 'THB' - | 'TJS' - | 'TMT' - | 'TND' - | 'TOP' - | 'TRY' - | 'TTD' - | 'TVD' - | 'TWD' - | 'TZS' - | 'UAH' - | 'UGX' - | 'USD' - | 'UYU' - | 'UZS' - | 'VEF' - | 'VND' - | 'VUV' - | 'WST' - | 'XAF' - | 'XCD' - | 'XOF' - | 'XPF' - | 'YER' - | 'ZAR' - | 'ZMW' - | 'LOGICAL' - | 'CUSTOM'; - - /** - * Posted timestamp of the parent transaction in ISO 8601 format. - */ - posted: string; - - /** - * Reference to a transaction by encoded ID and external ID. - */ - transaction: Payment.Transaction; - - /** - * The type of the payment. - */ - type: 'payin' | 'payout'; - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - user: Payment.User; - } - - export namespace Payment { - /** - * Reference to a transaction by encoded ID and external ID. - */ - export interface Transaction { - /** - * Encoded transaction ID. - */ - id: string; - - /** - * External transaction ID. - */ - external_id: string; - - /** - * Metadata tags from the parent transaction. - */ - tags: Array; - } - - export namespace Transaction { - /** - * A key-value tag pair - */ - export interface Tag { - /** - * Tag key - */ - key: string; - - /** - * Tag value - */ - value: string; - } - } - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - export interface User { - /** - * FRAGMENT generated ID of the user - */ - id: string; - - /** - * External ID of the user - */ - external_id?: string; - } - } - - export interface User { - /** - * User/party ID - */ - id: string; - - /** - * Per-currency balance breakdown for this user - */ - balances: Array; - } - - export namespace User { - export interface Balance { - /** - * Currency code - */ - currency: string; - - net: Balance.Net; - - payins: Balance.Payins; - - payouts: Balance.Payouts; - } - - export namespace Balance { - export interface Net { - /** - * Actual amount (represented as string) - */ - actual: string; - - /** - * Expected amount (represented as string) - */ - expected: string; - - /** - * Remaining amount (expected - actual, represented as string) - */ - remaining: string; - } - - export interface Payins { - /** - * Actual amount (represented as string) - */ - actual: string; - - /** - * Expected amount (represented as string) - */ - expected: string; - - /** - * Remaining amount (expected - actual, represented as string) - */ - remaining: string; - } - - export interface Payouts { - /** - * Actual amount (represented as string) - */ - actual: string; - - /** - * Expected amount (represented as string) - */ - expected: string; - - /** - * Remaining amount (expected - actual, represented as string) - */ - remaining: string; - } - } - } - } -} - -export interface InvoiceUpdateResponse { - /** - * Invoice object - */ - data: Invoice; -} - -/** - * List of invoices - */ -export interface InvoiceListResponse { - data: Array; -} - -/** - * Version history of an invoice - */ -export interface InvoiceListHistoryResponse { - data: Array; -} - -export namespace InvoiceListHistoryResponse { - /** - * A versioned snapshot of an invoice - */ - export interface Data extends Omit { - /** - * Cumulative diff of changes applied to the invoice - */ - diff?: Array; - - /** - * Version number of this invoice snapshot - */ - version?: number; - } - - export namespace Data { - export interface AddDiffEntry { - /** - * Invoice line item object - */ - item: AddDiffEntry.Item; - - /** - * A line item was added - */ - op: 'add'; - } - - export namespace AddDiffEntry { - /** - * Invoice line item object - */ - export interface Item { - /** - * Unique identifier for the line item - */ - id: string; - - /** - * @deprecated Deprecated: use price.amount instead. Total amount in smallest - * currency unit (represented as string for bigint) - */ - amount: string; - - /** - * Currency code (ISO 4217 or crypto) - */ - currency_code: - | 'ADA' - | 'BTC' - | 'DAI' - | 'ETH' - | 'SOL' - | 'USDC' - | 'USDT' - | 'USDG' - | 'EURC' - | 'CADC' - | 'CADT' - | 'XLM' - | 'UNI' - | 'BCH' - | 'LTC' - | 'AAVE' - | 'LINK' - | 'MATIC' - | 'PTS' - | 'AED' - | 'AFN' - | 'ALL' - | 'AMD' - | 'ANG' - | 'AOA' - | 'ARS' - | 'AUD' - | 'AWG' - | 'AZN' - | 'BAM' - | 'BBD' - | 'BDT' - | 'BGN' - | 'BHD' - | 'BIF' - | 'BMD' - | 'BND' - | 'BOB' - | 'BRL' - | 'BSD' - | 'BTN' - | 'BWP' - | 'BYR' - | 'BZD' - | 'CAD' - | 'CDF' - | 'CHF' - | 'CLP' - | 'CNY' - | 'COP' - | 'CRC' - | 'CUC' - | 'CUP' - | 'CVE' - | 'CZK' - | 'DJF' - | 'DKK' - | 'DOP' - | 'DZD' - | 'EGP' - | 'ERN' - | 'ETB' - | 'EUR' - | 'FJD' - | 'FKP' - | 'GBP' - | 'GEL' - | 'GGP' - | 'GHS' - | 'GIP' - | 'GMD' - | 'GNF' - | 'GTQ' - | 'GYD' - | 'HKD' - | 'HNL' - | 'HRK' - | 'HTG' - | 'HUF' - | 'IDR' - | 'ILS' - | 'IMP' - | 'INR' - | 'IQD' - | 'IRR' - | 'ISK' - | 'JMD' - | 'JOD' - | 'JPY' - | 'KES' - | 'KGS' - | 'KHR' - | 'KMF' - | 'KPW' - | 'KRW' - | 'KWD' - | 'KYD' - | 'KZT' - | 'LAK' - | 'LBP' - | 'LKR' - | 'LRD' - | 'LSL' - | 'LYD' - | 'MAD' - | 'MDL' - | 'MGA' - | 'MKD' - | 'MMK' - | 'MNT' - | 'MOP' - | 'MUR' - | 'MVR' - | 'MWK' - | 'MXN' - | 'MYR' - | 'MZN' - | 'NAD' - | 'NGN' - | 'NIO' - | 'NOK' - | 'NPR' - | 'NZD' - | 'OMR' - | 'PAB' - | 'PEN' - | 'PGK' - | 'PHP' - | 'PKR' - | 'PLN' - | 'PYG' - | 'QAR' - | 'RON' - | 'RSD' - | 'RUB' - | 'RWF' - | 'SAR' - | 'SBD' - | 'SCR' - | 'SDG' - | 'SEK' - | 'SGD' - | 'SHP' - | 'SLL' - | 'SOS' - | 'SPL' - | 'SRD' - | 'SVC' - | 'SYP' - | 'STN' - | 'SZL' - | 'THB' - | 'TJS' - | 'TMT' - | 'TND' - | 'TOP' - | 'TRY' - | 'TTD' - | 'TVD' - | 'TWD' - | 'TZS' - | 'UAH' - | 'UGX' - | 'USD' - | 'UYU' - | 'UZS' - | 'VEF' - | 'VND' - | 'VUV' - | 'WST' - | 'XAF' - | 'XCD' - | 'XOF' - | 'XPF' - | 'YER' - | 'ZAR' - | 'ZMW' - | 'LOGICAL' - | 'CUSTOM'; - - /** - * Description of the line item - */ - description: string; - - /** - * Price breakdown containing amount, unit price, and quantity - */ - price: Item.Price; - - /** - * ID of the product/catalog item - */ - product_id: string; - - /** - * Metadata tags for this line item - */ - tags: Array; - - /** - * The type of the line item - */ - type: 'payin' | 'payout'; - - /** - * External ID of the user associated with this line item - */ - user_id: string; - } - - export namespace Item { - /** - * Price breakdown containing amount, unit price, and quantity - */ - export interface Price { - /** - * Total amount in smallest currency unit (represented as string for bigint) - */ - amount: string; - - /** - * Quantity of units for this line item - */ - quantity: number; - - /** - * Unit price in smallest currency unit (represented as string for bigint) - */ - unit_price: string; - } - - /** - * A key-value tag pair - */ - export interface Tag { - /** - * Tag key - */ - key: string; - - /** - * Tag value - */ - value: string; - } - } - } - - export interface UpdateDiffEntry { - /** - * ID of the updated line item - */ - id: string; - - /** - * @deprecated Deprecated: use new_price.amount instead. New amount after the - * update - */ - new_amount: string; - - /** - * Price breakdown containing amount, unit price, and quantity - */ - new_price: UpdateDiffEntry.NewPrice; - - /** - * @deprecated Deprecated: use old_price.amount instead. Amount before the update - */ - old_amount: string; - - /** - * Price breakdown containing amount, unit price, and quantity - */ - old_price: UpdateDiffEntry.OldPrice; - - /** - * A line item was updated - */ - op: 'update'; - } - - export namespace UpdateDiffEntry { - /** - * Price breakdown containing amount, unit price, and quantity - */ - export interface NewPrice { - /** - * Total amount in smallest currency unit (represented as string for bigint) - */ - amount: string; - - /** - * Quantity of units for this line item - */ - quantity: number; - - /** - * Unit price in smallest currency unit (represented as string for bigint) - */ - unit_price: string; - } - - /** - * Price breakdown containing amount, unit price, and quantity - */ - export interface OldPrice { - /** - * Total amount in smallest currency unit (represented as string for bigint) - */ - amount: string; - - /** - * Quantity of units for this line item - */ - quantity: number; - - /** - * Unit price in smallest currency unit (represented as string for bigint) - */ - unit_price: string; - } - } - - export interface DeleteDiffEntry { - /** - * Invoice line item object - */ - item: DeleteDiffEntry.Item; - - /** - * A line item was deleted - */ - op: 'delete'; - } - - export namespace DeleteDiffEntry { - /** - * Invoice line item object - */ - export interface Item { - /** - * Unique identifier for the line item - */ - id: string; - - /** - * @deprecated Deprecated: use price.amount instead. Total amount in smallest - * currency unit (represented as string for bigint) - */ - amount: string; - - /** - * Currency code (ISO 4217 or crypto) - */ - currency_code: - | 'ADA' - | 'BTC' - | 'DAI' - | 'ETH' - | 'SOL' - | 'USDC' - | 'USDT' - | 'USDG' - | 'EURC' - | 'CADC' - | 'CADT' - | 'XLM' - | 'UNI' - | 'BCH' - | 'LTC' - | 'AAVE' - | 'LINK' - | 'MATIC' - | 'PTS' - | 'AED' - | 'AFN' - | 'ALL' - | 'AMD' - | 'ANG' - | 'AOA' - | 'ARS' - | 'AUD' - | 'AWG' - | 'AZN' - | 'BAM' - | 'BBD' - | 'BDT' - | 'BGN' - | 'BHD' - | 'BIF' - | 'BMD' - | 'BND' - | 'BOB' - | 'BRL' - | 'BSD' - | 'BTN' - | 'BWP' - | 'BYR' - | 'BZD' - | 'CAD' - | 'CDF' - | 'CHF' - | 'CLP' - | 'CNY' - | 'COP' - | 'CRC' - | 'CUC' - | 'CUP' - | 'CVE' - | 'CZK' - | 'DJF' - | 'DKK' - | 'DOP' - | 'DZD' - | 'EGP' - | 'ERN' - | 'ETB' - | 'EUR' - | 'FJD' - | 'FKP' - | 'GBP' - | 'GEL' - | 'GGP' - | 'GHS' - | 'GIP' - | 'GMD' - | 'GNF' - | 'GTQ' - | 'GYD' - | 'HKD' - | 'HNL' - | 'HRK' - | 'HTG' - | 'HUF' - | 'IDR' - | 'ILS' - | 'IMP' - | 'INR' - | 'IQD' - | 'IRR' - | 'ISK' - | 'JMD' - | 'JOD' - | 'JPY' - | 'KES' - | 'KGS' - | 'KHR' - | 'KMF' - | 'KPW' - | 'KRW' - | 'KWD' - | 'KYD' - | 'KZT' - | 'LAK' - | 'LBP' - | 'LKR' - | 'LRD' - | 'LSL' - | 'LYD' - | 'MAD' - | 'MDL' - | 'MGA' - | 'MKD' - | 'MMK' - | 'MNT' - | 'MOP' - | 'MUR' - | 'MVR' - | 'MWK' - | 'MXN' - | 'MYR' - | 'MZN' - | 'NAD' - | 'NGN' - | 'NIO' - | 'NOK' - | 'NPR' - | 'NZD' - | 'OMR' - | 'PAB' - | 'PEN' - | 'PGK' - | 'PHP' - | 'PKR' - | 'PLN' - | 'PYG' - | 'QAR' - | 'RON' - | 'RSD' - | 'RUB' - | 'RWF' - | 'SAR' - | 'SBD' - | 'SCR' - | 'SDG' - | 'SEK' - | 'SGD' - | 'SHP' - | 'SLL' - | 'SOS' - | 'SPL' - | 'SRD' - | 'SVC' - | 'SYP' - | 'STN' - | 'SZL' - | 'THB' - | 'TJS' - | 'TMT' - | 'TND' - | 'TOP' - | 'TRY' - | 'TTD' - | 'TVD' - | 'TWD' - | 'TZS' - | 'UAH' - | 'UGX' - | 'USD' - | 'UYU' - | 'UZS' - | 'VEF' - | 'VND' - | 'VUV' - | 'WST' - | 'XAF' - | 'XCD' - | 'XOF' - | 'XPF' - | 'YER' - | 'ZAR' - | 'ZMW' - | 'LOGICAL' - | 'CUSTOM'; + | 'NPR' + | 'NZD' + | 'OMR' + | 'PAB' + | 'PEN' + | 'PGK' + | 'PHP' + | 'PKR' + | 'PLN' + | 'PYG' + | 'QAR' + | 'RON' + | 'RSD' + | 'RUB' + | 'RWF' + | 'SAR' + | 'SBD' + | 'SCR' + | 'SDG' + | 'SEK' + | 'SGD' + | 'SHP' + | 'SLL' + | 'SOS' + | 'SPL' + | 'SRD' + | 'SVC' + | 'SYP' + | 'STN' + | 'SZL' + | 'THB' + | 'TJS' + | 'TMT' + | 'TND' + | 'TOP' + | 'TRY' + | 'TTD' + | 'TVD' + | 'TWD' + | 'TZS' + | 'UAH' + | 'UGX' + | 'USD' + | 'UYU' + | 'UZS' + | 'VEF' + | 'VND' + | 'VUV' + | 'WST' + | 'XAF' + | 'XCD' + | 'XOF' + | 'XPF' + | 'YER' + | 'ZAR' + | 'ZMW' + | 'LOGICAL' + | 'CUSTOM'; + + /** + * Timestamp when the parent transaction was posted. Uses ISO 8601 format. + */ + posted: string; + + /** + * Transaction the payment is applied to. + */ + transaction: Payment.Transaction; + + /** + * Type of the payment. + */ + type: 'payin' | 'payout'; + + /** + * User associated with the payment. + */ + user: Payment.User; + } + + export namespace Payment { + /** + * Transaction the payment is applied to. + */ + export interface Transaction { + /** + * FRAGMENT generated unique ID. + */ + id: string; + + /** + * User-provided unique ID. + */ + external_id: string; + + /** + * Tags from the parent transaction. + */ + tags: Array; + } + export namespace Transaction { /** - * Description of the line item + * A key-value tag pair. */ - description: string; + export interface Tag { + /** + * Tag key. + */ + key: string; + + /** + * Tag value. + */ + value: string; + } + } + /** + * User associated with the payment. + */ + export interface User { /** - * Price breakdown containing amount, unit price, and quantity + * FRAGMENT generated unique ID. */ - price: Item.Price; + id: string; /** - * ID of the product/catalog item + * User-provided unique ID. */ - product_id: string; + external_id: string; + } + } + + export interface User { + /** + * User-provided unique external ID. + */ + id: string; + + /** + * Per-currency balance breakdown for the user. + */ + balances: Array; + + /** + * User-provided unique ID. + */ + external_id: string; + } + export namespace User { + export interface Balance { /** - * Metadata tags for this line item + * ISO 4217 or crypto currency code. */ - tags: Array; + currency: string; /** - * The type of the line item + * Net balance breakdown. */ - type: 'payin' | 'payout'; + net: Balance.Net; + + /** + * Payins balance breakdown. + */ + payins: Balance.Payins; /** - * External ID of the user associated with this line item + * Payouts balance breakdown. */ - user_id: string; + payouts: Balance.Payouts; } - export namespace Item { + export namespace Balance { /** - * Price breakdown containing amount, unit price, and quantity + * Net balance breakdown. */ - export interface Price { + export interface Net { /** - * Total amount in smallest currency unit (represented as string for bigint) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ - amount: string; + actual: string; /** - * Quantity of units for this line item + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ - quantity: number; + expected: string; /** - * Unit price in smallest currency unit (represented as string for bigint) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ - unit_price: string; + remaining: string; } /** - * A key-value tag pair + * Payins balance breakdown. */ - export interface Tag { + export interface Payins { /** - * Tag key + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ - key: string; + actual: string; /** - * Tag value + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ - value: string; + expected: string; + + /** + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. + */ + remaining: string; + } + + /** + * Payouts balance breakdown. + */ + export interface Payouts { + /** + * Actual amount as a string in the smallest currency unit, such as cents for USD. + */ + actual: string; + + /** + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. + */ + expected: string; + + /** + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. + */ + remaining: string; } } } } } +export interface InvoiceUpdateResponse { + /** + * Invoice object. + */ + data: Invoice; +} + +export interface InvoiceListResponse { + /** + * List of invoices. + */ + data: Array; +} + +export interface InvoiceListHistoryResponse { + /** + * Version history of the invoice. + */ + data: Array; +} + /** - * Response body for searching invoices + * Search results for invoices. */ export interface InvoiceSearchResponse { + /** + * Search results for invoices. + */ data: InvoiceSearchResponse.Data; } export namespace InvoiceSearchResponse { + /** + * Search results for invoices. + */ export interface Data { /** - * List of invoices matching the search criteria + * Invoices matching the search criteria. */ invoices: Array; @@ -1584,21 +986,21 @@ export namespace InvoiceSearchResponse { export namespace Data { /** - * Invoice with balance details + * Invoice with balance details. */ export interface Invoice extends InvoicesAPI.Invoice { /** - * Invoice-level balances by currency: payins, payouts, and net (payins - payouts) + * Invoice-level balances by currency. */ balances: Array; /** - * Transaction allocations (payments) associated with this invoice. + * Payments allocated to the invoice. */ payments: Array; /** - * Users/parties involved in the invoice + * Users involved in the invoice. */ users: Array; } @@ -1606,81 +1008,106 @@ export namespace InvoiceSearchResponse { export namespace Invoice { export interface Balance { /** - * Currency code + * ISO 4217 or crypto currency code. */ currency: string; + /** + * Net balance breakdown. + */ net: Balance.Net; + /** + * Payins balance breakdown. + */ payins: Balance.Payins; + /** + * Payouts balance breakdown. + */ payouts: Balance.Payouts; } export namespace Balance { + /** + * Net balance breakdown. + */ export interface Net { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payins balance breakdown. + */ export interface Payins { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payouts balance breakdown. + */ export interface Payouts { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } } /** - * A payment allocated to this invoice. + * A payment allocated to the invoice. */ export interface Payment { /** - * Amount allocated in smallest currency unit as stringified bigint. + * Amount allocated as a string in the smallest currency unit, such as cents for + * USD. */ amount: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency: | 'ADA' @@ -1864,154 +1291,183 @@ export namespace InvoiceSearchResponse { | 'CUSTOM'; /** - * Posted timestamp of the parent transaction in ISO 8601 format. + * Timestamp when the parent transaction was posted. Uses ISO 8601 format. */ posted: string; /** - * Reference to a transaction by encoded ID and external ID. + * Transaction the payment is applied to. */ transaction: Payment.Transaction; /** - * The type of the payment. + * Type of the payment. */ type: 'payin' | 'payout'; /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the payment. */ user: Payment.User; } export namespace Payment { /** - * Reference to a transaction by encoded ID and external ID. + * Transaction the payment is applied to. */ export interface Transaction { /** - * Encoded transaction ID. + * FRAGMENT generated unique ID. */ id: string; /** - * External transaction ID. + * User-provided unique ID. */ external_id: string; /** - * Metadata tags from the parent transaction. + * Tags from the parent transaction. */ tags: Array; } export namespace Transaction { /** - * A key-value tag pair + * A key-value tag pair. */ export interface Tag { /** - * Tag key + * Tag key. */ key: string; /** - * Tag value + * Tag value. */ value: string; } } /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the payment. */ export interface User { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; /** - * External ID of the user + * User-provided unique ID. */ - external_id?: string; + external_id: string; } } export interface User { /** - * User/party ID + * User-provided unique external ID. */ id: string; /** - * Per-currency balance breakdown for this user + * Per-currency balance breakdown for the user. */ balances: Array; + + /** + * User-provided unique ID. + */ + external_id: string; } export namespace User { export interface Balance { /** - * Currency code + * ISO 4217 or crypto currency code. */ currency: string; + /** + * Net balance breakdown. + */ net: Balance.Net; + /** + * Payins balance breakdown. + */ payins: Balance.Payins; + /** + * Payouts balance breakdown. + */ payouts: Balance.Payouts; } export namespace Balance { + /** + * Net balance breakdown. + */ export interface Net { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payins balance breakdown. + */ export interface Payins { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } + /** + * Payouts balance breakdown. + */ export interface Payouts { /** - * Actual amount (represented as string) + * Actual amount as a string in the smallest currency unit, such as cents for USD. */ actual: string; /** - * Expected amount (represented as string) + * Expected amount as a string in the smallest currency unit, such as cents for + * USD. */ expected: string; /** - * Remaining amount (expected - actual, represented as string) + * Remaining amount as a string in the smallest currency unit, such as cents for + * USD. */ remaining: string; } @@ -2024,7 +1480,7 @@ export namespace InvoiceSearchResponse { */ export interface PageInfo { /** - * Cursor to fetch the next page of results + * Cursor to fetch the next page of results. */ next_cursor?: string; } @@ -2033,18 +1489,17 @@ export namespace InvoiceSearchResponse { export interface InvoiceCreateParams { /** - * Unique identifier for the invoice. Make this the canonical ID from your system - * for the transaction. + * Unique ID for the invoice. */ invoice_id: string; /** - * List of line items to create with the invoice + * Line items to create with the invoice. */ line_items: Array; /** - * Optional metadata tags for this invoice + * Tags for the invoice. */ tags?: Array; } @@ -2055,33 +1510,33 @@ export namespace InvoiceCreateParams { */ export interface LineItem { /** - * Description of the line item + * Description of the line item. */ description: string; /** - * ID of the product/catalog item + * Unique identifier for the product. */ product_id: string; /** - * The type of the line item + * Type of the line item. */ type: 'payin' | 'payout'; /** - * Identifies a user by Fragment-generated id or external_id (request body). + * Identifies a user by `id` or `external_id`. */ user: LineItem.ID | LineItem.ExternalID; /** - * @deprecated Deprecated: use price instead. Total amount in smallest currency - * unit. + * @deprecated Total amount as a string in the smallest currency unit, such as + * cents for USD. Deprecated, use price instead. */ amount?: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency_code?: | 'ADA' @@ -2265,12 +1720,12 @@ export namespace InvoiceCreateParams { | 'CUSTOM'; /** - * Price breakdown. Provide amount, or unit_price + quantity, or all three. + * Price breakdown. Provide amount, or unit_price and quantity, or all three. */ price?: LineItem.Price; /** - * Optional metadata tags for this line item + * Tags for the line item. */ tags?: Array; } @@ -2278,70 +1733,66 @@ export namespace InvoiceCreateParams { export namespace LineItem { export interface ID { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; } export interface ExternalID { /** - * External ID of the user + * User-provided unique ID. */ external_id: string; } /** - * Price breakdown. Provide amount, or unit_price + quantity, or all three. + * Price breakdown. Provide amount, or unit_price and quantity, or all three. */ export interface Price { /** - * Total amount in smallest currency unit. Required if unit_price and quantity are - * not provided. + * Total amount as a string in the smallest currency unit, such as cents for USD. + * Required if unit_price and quantity are not provided. */ amount?: string; /** - * Number of units for this line item. + * Number of units for the line item. */ quantity?: number; /** - * Price per unit in smallest currency unit. + * Price per unit as a string in the smallest currency unit, such as cents for USD. */ unit_price?: string; } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Tag { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Tag { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -2349,30 +1800,38 @@ export namespace InvoiceCreateParams { export interface InvoiceUpdateParams { /** - * The current version of the invoice. Must match the stored version for the update - * to succeed (optimistic concurrency). + * Current version of the invoice. Must match the stored version. */ current_invoice_version: number; + /** + * Line item updates. + */ line_items?: InvoiceUpdateParams.LineItems; + /** + * Tag updates. + */ tags?: InvoiceUpdateParams.Tags; } export namespace InvoiceUpdateParams { + /** + * Line item updates. + */ export interface LineItems { /** - * Line items to add to the invoice + * Line items to add to the invoice. */ create?: Array; /** - * Line items to remove from the invoice + * Line items to remove from the invoice. */ delete?: Array; /** - * Existing line items to update + * Existing line items to update. */ update?: Array; } @@ -2383,33 +1842,33 @@ export namespace InvoiceUpdateParams { */ export interface Create { /** - * Description of the line item + * Description of the line item. */ description: string; /** - * ID of the product/catalog item + * Unique identifier for the product. */ product_id: string; /** - * The type of the line item + * Type of the line item. */ type: 'payin' | 'payout'; /** - * Identifies a user by Fragment-generated id or external_id (request body). + * Identifies a user by `id` or `external_id`. */ user: Create.ID | Create.ExternalID; /** - * @deprecated Deprecated: use price instead. Total amount in smallest currency - * unit. + * @deprecated Total amount as a string in the smallest currency unit, such as + * cents for USD. Deprecated, use price instead. */ amount?: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency_code?: | 'ADA' @@ -2593,12 +2052,12 @@ export namespace InvoiceUpdateParams { | 'CUSTOM'; /** - * Price breakdown. Provide amount, or unit_price + quantity, or all three. + * Price breakdown. Provide amount, or unit_price and quantity, or all three. */ price?: Create.Price; /** - * Optional metadata tags for this line item + * Tags for the line item. */ tags?: Array; } @@ -2606,52 +2065,50 @@ export namespace InvoiceUpdateParams { export namespace Create { export interface ID { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; } export interface ExternalID { /** - * External ID of the user + * User-provided unique ID. */ external_id: string; } /** - * Price breakdown. Provide amount, or unit_price + quantity, or all three. + * Price breakdown. Provide amount, or unit_price and quantity, or all three. */ export interface Price { /** - * Total amount in smallest currency unit. Required if unit_price and quantity are - * not provided. + * Total amount as a string in the smallest currency unit, such as cents for USD. + * Required if unit_price and quantity are not provided. */ amount?: string; /** - * Number of units for this line item. + * Number of units for the line item. */ quantity?: number; /** - * Price per unit in smallest currency unit. + * Price per unit as a string in the smallest currency unit, such as cents for USD. */ unit_price?: string; } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Tag { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -2659,17 +2116,17 @@ export namespace InvoiceUpdateParams { export interface Delete { /** - * ID of the line item to delete + * Unique identifier for the line item to delete. */ id: string; } /** - * Partial update for an existing line item. All fields except id are optional. + * Data for updating a line item. */ export interface Update { /** - * ID of the line item to update + * Unique identifier for the line item to update. */ id: string; @@ -2677,82 +2134,104 @@ export namespace InvoiceUpdateParams { price?: Update.Price; + /** + * Tag updates. + */ tags?: Update.Tags; } export namespace Update { export interface Price { /** - * Number of units for this line item. + * Number of units for the line item. */ quantity: number; /** - * Price per unit in smallest currency unit. + * Price per unit as a string in the smallest currency unit, such as cents for USD. */ unit_price: string; /** - * Total amount in smallest currency unit. + * Total amount as a string in the smallest currency unit, such as cents for USD. */ amount?: string; } + /** + * Tag updates. + */ export interface Tags { /** - * Tags to add + * Tags to create. The tag key must not already exist. */ create?: Array; /** - * Tags to remove by key + * Tags to remove. */ delete?: Array; /** - * Tags to update. The key identifies the existing tag; the value is the new value. + * Tags to set. Creates a new tag or updates an existing tag. + */ + set?: Array; + + /** + * Tags to update. The tag key must already exist. */ update?: Array; } export namespace Tags { /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Create { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } export interface Delete { /** - * Tag key to delete + * Tag key to delete. + */ + key: string; + } + + /** + * A key-value tag pair for metadata. + */ + export interface Set { + /** + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; + + /** + * Tag value. Must not contain #, /, or :. Max 200 characters. + */ + value: string; } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Update { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -2760,61 +2239,80 @@ export namespace InvoiceUpdateParams { } } + /** + * Tag updates. + */ export interface Tags { /** - * Tags to add + * Tags to create. The tag key must not already exist. */ create?: Array; /** - * Tags to remove by key + * Tags to remove. */ delete?: Array; /** - * Tags to update. The key identifies the existing tag; the value is the new value. + * Tags to set. Creates a new tag or updates an existing tag. + */ + set?: Array; + + /** + * Tags to update. The tag key must already exist. */ update?: Array; } export namespace Tags { /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Create { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } export interface Delete { /** - * Tag key to delete + * Tag key to delete. + */ + key: string; + } + + /** + * A key-value tag pair for metadata. + */ + export interface Set { + /** + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; + + /** + * Tag value. Must not contain #, /, or :. Max 200 characters. + */ + value: string; } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Update { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -2823,19 +2321,19 @@ export namespace InvoiceUpdateParams { export interface InvoiceSearchParams { /** - * Filter criteria for the search + * Filter criteria for the search. */ filter: InvoiceSearchParams.Filter; /** - * Pagination parameters + * Pagination parameters. */ - page_info: InvoiceSearchParams.PageInfo; + page_info?: InvoiceSearchParams.PageInfo; } export namespace InvoiceSearchParams { /** - * Filter criteria for the search + * Filter criteria for the search. */ export interface Filter { /** @@ -2858,12 +2356,12 @@ export namespace InvoiceSearchParams { */ export interface Tags { /** - * Returns invoices matching every specified tag (AND). + * Returns invoices matching every specified tag, using AND logic. */ all?: Array; /** - * Returns invoices matching at least one of the specified tags (OR). + * Returns invoices matching at least one of the specified tags, using OR logic. */ any?: Array; } @@ -2906,11 +2404,11 @@ export namespace InvoiceSearchParams { } /** - * Pagination parameters + * Pagination parameters. */ export interface PageInfo { /** - * Cursor for fetching the next page of results + * Cursor for fetching the next page of results. */ after?: string; diff --git a/src/resources/products.ts b/src/resources/products.ts index cf063a8..9c2443a 100644 --- a/src/resources/products.ts +++ b/src/resources/products.ts @@ -10,7 +10,7 @@ import { path } from '../internal/utils/path'; */ export class Products extends APIResource { /** - * Creates a new product + * Creates a product. * * @example * ```ts @@ -24,7 +24,7 @@ export class Products extends APIResource { } /** - * Gets a product by code + * Retrieves a product by code. * * @example * ```ts @@ -36,7 +36,7 @@ export class Products extends APIResource { } /** - * Lists all products for the workspace + * Lists all products. * * @example * ```ts @@ -49,46 +49,46 @@ export class Products extends APIResource { } /** - * Product object + * Product object. */ export interface Product { /** - * Unique identifier for the product + * FRAGMENT generated unique ID. */ id: string; /** - * User-defined product identifier. + * Product code. */ code: string; /** - * ISO 8601 timestamp when the product was created + * Timestamp when the product was created. Uses ISO 8601 format. */ created: string; /** - * User roles that can pay for this product + * Roles that can pay for the product. */ paid_by_roles: Array; /** - * User roles that receive payment for this product + * Roles that can receive payment for the product. */ paid_to_roles: Array; /** - * Version number for optimistic locking + * Current version of the product. */ update_version: number; /** - * Workspace ID this product belongs to + * Workspace ID of the product. */ workspace_id: string; /** - * Description of the product + * Product description. */ description?: string; } @@ -99,12 +99,12 @@ export namespace Product { */ export interface PaidByRole { /** - * The unique ID of the role + * FRAGMENT generated unique ID. */ id: string; /** - * The name of the role + * Name of the role. */ name: string; } @@ -114,12 +114,12 @@ export namespace Product { */ export interface PaidToRole { /** - * The unique ID of the role + * FRAGMENT generated unique ID. */ id: string; /** - * The name of the role + * Name of the role. */ name: string; } @@ -127,45 +127,45 @@ export namespace Product { export interface ProductCreateResponse { /** - * Product object + * Product object. */ data: Product; } export interface ProductRetrieveResponse { /** - * Product object + * Product object. */ data: Product; } -/** - * List of products - */ export interface ProductListResponse { + /** + * List of products. + */ data: Array; } export interface ProductCreateParams { /** - * Product code (unique identifier) + * Unique product code. */ code: string; /** - * Description of the product + * Product description. */ description?: string; /** - * Roles that can pay for this product. Reference roles by id or name. At least one - * of paid_by_roles or paid_to_roles must be provided. + * Roles that can pay for the product. Reference roles by `id` or `name`. At least + * one of `paid_by_roles` or `paid_to_roles` must be provided. */ paid_by_roles?: Array; /** - * Roles that receive payment for this product. Reference roles by id or name. At - * least one of paid_by_roles or paid_to_roles must be provided. + * Roles that can receive payment for the product. Reference roles by `id` or + * `name`. At least one of `paid_by_roles` or `paid_to_roles` must be provided. */ paid_to_roles?: Array; } @@ -173,28 +173,28 @@ export interface ProductCreateParams { export namespace ProductCreateParams { export interface ID { /** - * The unique ID of the role + * FRAGMENT generated unique ID. */ id: string; } export interface Name { /** - * The name of the role + * Name of the role. */ name: string; } export interface ID { /** - * The unique ID of the role + * FRAGMENT generated unique ID. */ id: string; } export interface Name { /** - * The name of the role + * Name of the role. */ name: string; } diff --git a/src/resources/roles.ts b/src/resources/roles.ts index b9b9730..75ad303 100644 --- a/src/resources/roles.ts +++ b/src/resources/roles.ts @@ -9,7 +9,7 @@ import { RequestOptions } from '../internal/request-options'; */ export class Roles extends APIResource { /** - * Creates a new role + * Creates a role. * * @example * ```ts @@ -21,7 +21,7 @@ export class Roles extends APIResource { } /** - * Lists all roles for the workspace + * Lists all roles. * * @example * ```ts @@ -34,37 +34,40 @@ export class Roles extends APIResource { } /** - * Role object + * Role object. */ export interface Role { /** - * Unique role ID + * FRAGMENT generated unique ID. */ id: string; /** - * Name of the role + * Name of the role. */ role: string; } export interface RoleCreateResponse { /** - * Role object + * Role object. */ data: Role; } /** - * List of roles + * List of roles. */ export interface RoleListResponse { + /** + * List of roles. + */ data: Array; } export interface RoleCreateParams { /** - * Name of the role + * Name of the role. */ role: string; } diff --git a/src/resources/transactions.ts b/src/resources/transactions.ts index 13a6d1a..bf2af2a 100644 --- a/src/resources/transactions.ts +++ b/src/resources/transactions.ts @@ -11,7 +11,7 @@ import { path } from '../internal/utils/path'; */ export class Transactions extends APIResource { /** - * Syncs a transaction, optionally with allocations + * Creates a transaction. * * @example * ```ts @@ -28,7 +28,7 @@ export class Transactions extends APIResource { * amount: '-1000', * currency: 'USD', * external_id: 'bank_txn_123', - * posted: '2026-02-12T00:00:00.000Z', + * posted: '2024-01-13T00:00:00Z', * }); * ``` */ @@ -37,7 +37,7 @@ export class Transactions extends APIResource { } /** - * Gets a transaction by ID or external ID + * Retrieves a transaction by ID or external ID. * * @example * ```ts @@ -51,7 +51,7 @@ export class Transactions extends APIResource { } /** - * Updates a transaction (tags, allocations, or both) + * Updates a transaction. * * @example * ```ts @@ -70,7 +70,7 @@ export class Transactions extends APIResource { } /** - * Lists all transactions for the workspace + * Lists all transactions. * * @example * ```ts @@ -85,38 +85,7 @@ export class Transactions extends APIResource { } /** - * Updates allocations on an existing transaction - * - * @example - * ```ts - * const response = - * await client.transactions.createAllocations( - * 'txn_abc123', - * { - * allocation_updates: [ - * { - * amount: '1000', - * invoice_id: 'inv_abc123', - * op: 'add', - * type: 'invoice_payin', - * user: { id: 'user_abc123' }, - * }, - * ], - * version: 0, - * }, - * ); - * ``` - */ - createAllocations( - transactionRef: string, - body: TransactionCreateAllocationsParams, - options?: RequestOptions, - ): APIPromise { - return this._client.post(path`/transactions/${transactionRef}/allocations`, { body, ...options }); - } - - /** - * Gets the version history of a transaction + * Retrieves the version history of a transaction. * * @example * ```ts @@ -130,12 +99,12 @@ export class Transactions extends APIResource { } /** - * Searches transactions by filter criteria + * Searches transactions. * * @example * ```ts * const response = await client.transactions.search({ - * filter: { account: { any: [{}] } }, + * filter: {}, * }); * ``` */ @@ -144,7 +113,7 @@ export class Transactions extends APIResource { } /** - * Searches transaction allocations by filter criteria + * Searches transaction allocations. * * @example * ```ts @@ -167,30 +136,33 @@ export class Transactions extends APIResource { */ export interface Transaction { /** - * User-facing encoded transaction ID. + * FRAGMENT generated unique ID. */ id: string; /** - * External account reference on transaction responses. + * External account for the transaction. */ account: Transaction.Account; + /** + * Allocations applied to the transaction. + */ allocations: Array; /** - * Amount in smallest currency unit as stringified bigint (can be positive or - * negative). + * Transaction amount, as a string in the smallest currency unit, such as cents for + * USD. Can be positive or negative. */ amount: string; /** - * Creation timestamp. + * Timestamp when the transaction was created. Uses ISO 8601 format. */ created: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency: | 'ADA' @@ -374,105 +346,106 @@ export interface Transaction { | 'CUSTOM'; /** - * External idempotency key provided by the user. + * User-provided unique ID. */ external_id: string; /** - * Posted timestamp in ISO 8601 format. + * Timestamp when the transaction was posted. Uses ISO 8601 format. */ posted: string; /** - * Metadata tags associated with this transaction. + * Tags for the transaction. */ tags: Array; /** - * Read-only amount not yet allocated. + * Amount not yet allocated, as a string. */ unallocated_amount: string; /** - * Current version of the transaction, used for optimistic concurrency control. + * Current version of the transaction. */ version: number; /** - * Last modified timestamp. + * Timestamp when the transaction was last modified. Uses ISO 8601 format. */ modified?: string; } export namespace Transaction { /** - * External account reference on transaction responses. + * External account for the transaction. */ export interface Account { /** - * User-facing encoded account ID. + * FRAGMENT generated unique ID. */ id: string; /** - * External account reference ID. + * User-provided unique ID. */ external_id: string; } /** - * Transaction allocation against an invoice. + * An allocation linking a transaction to an invoice. */ export interface Allocation { /** - * Allocated amount in smallest currency unit as stringified bigint. + * Allocated amount, as a positive string in the smallest currency unit, such as + * cents for USD. */ amount: string; /** - * The invoice this allocation is applied against. + * Invoice the allocation is applied against. */ invoice_id: string; /** - * The type of allocation. + * Type of allocation. */ type: 'invoice_payin' | 'invoice_payout'; /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the allocation. */ user: Allocation.User; } export namespace Allocation { /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the allocation. */ export interface User { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; /** - * External ID of the user + * User-provided unique ID. */ - external_id?: string; + external_id: string; } } /** - * A key-value tag pair + * A key-value tag pair. */ export interface Tag { /** - * Tag key + * Tag key. */ key: string; /** - * Tag value + * Tag value. */ value: string; } @@ -499,446 +472,158 @@ export interface TransactionUpdateResponse { data: Transaction; } -/** - * List of transactions - */ export interface TransactionListResponse { - data: Array; -} - -export interface TransactionCreateAllocationsResponse { /** - * Transaction object. + * List of transaction objects matching the filter criteria. */ - data: Transaction; + data: Array; } -/** - * Version history of a transaction - */ export interface TransactionListHistoryResponse { - data: Array; -} - -export namespace TransactionListHistoryResponse { /** - * A versioned snapshot of a transaction + * List of transaction versions over time, ordered by version, oldest first. */ - export interface Data extends Omit { - /** - * Allocation changes applied in this version. Absent on version 1 (initial - * creation). Each entry describes an allocation that was added or deleted. - */ - diff?: Array< - Data.AddAllocationDiffEntry | Data.DeleteAllocationDiffEntry | Data.UpdateAllocationDiffEntry - >; - - /** - * Version number of this transaction snapshot. - */ - version?: number; - } - - export namespace Data { - export interface AddAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - item: AddAllocationDiffEntry.Item; - - /** - * An allocation was added - */ - op: 'add'; - } - - export namespace AddAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - export interface Item { - /** - * Allocated amount in smallest currency unit as stringified bigint. - */ - amount: string; - - /** - * The invoice this allocation is applied against. - */ - invoice_id: string; - - /** - * The type of allocation. - */ - type: 'invoice_payin' | 'invoice_payout'; - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - user: Item.User; - } - - export namespace Item { - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - export interface User { - /** - * FRAGMENT generated ID of the user - */ - id: string; - - /** - * External ID of the user - */ - external_id?: string; - } - } - } - - export interface DeleteAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - item: DeleteAllocationDiffEntry.Item; - - /** - * An allocation was deleted - */ - op: 'delete'; - } - - export namespace DeleteAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - export interface Item { - /** - * Allocated amount in smallest currency unit as stringified bigint. - */ - amount: string; - - /** - * The invoice this allocation is applied against. - */ - invoice_id: string; - - /** - * The type of allocation. - */ - type: 'invoice_payin' | 'invoice_payout'; - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - user: Item.User; - } - - export namespace Item { - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - export interface User { - /** - * FRAGMENT generated ID of the user - */ - id: string; - - /** - * External ID of the user - */ - external_id?: string; - } - } - } - - export interface UpdateAllocationDiffEntry { - /** - * The ID of the updated allocation. - */ - id: string; - - /** - * New amount in smallest currency unit as stringified bigint. - */ - new_amount: string; - - /** - * Previous amount in smallest currency unit as stringified bigint. - */ - old_amount: string; - - /** - * An allocation was updated - */ - op: 'update'; - } - } + data: Array; } -/** - * Search results for transactions. - */ export interface TransactionSearchResponse { - data: Array; + /** + * @deprecated Deprecated. Use `data_v2.transactions` instead. Returns the full + * unpaginated list of matching transactions. + */ + data: Array; + + data_v2: TransactionSearchResponse.DataV2; } export namespace TransactionSearchResponse { - /** - * A versioned snapshot of a transaction - */ - export interface Data extends Omit { + export interface DataV2 { /** - * Allocation changes applied in this version. Absent on version 1 (initial - * creation). Each entry describes an allocation that was added or deleted. + * Pagination cursors. */ - diff?: Array< - Data.AddAllocationDiffEntry | Data.DeleteAllocationDiffEntry | Data.UpdateAllocationDiffEntry - >; + page_info: DataV2.PageInfo; /** - * Version number of this transaction snapshot. + * Transactions matching the search criteria. */ - version?: number; + transactions: Array; } - export namespace Data { - export interface AddAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - item: AddAllocationDiffEntry.Item; - - /** - * An allocation was added - */ - op: 'add'; - } - - export namespace AddAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - export interface Item { - /** - * Allocated amount in smallest currency unit as stringified bigint. - */ - amount: string; - - /** - * The invoice this allocation is applied against. - */ - invoice_id: string; - - /** - * The type of allocation. - */ - type: 'invoice_payin' | 'invoice_payout'; - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - user: Item.User; - } - - export namespace Item { - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - export interface User { - /** - * FRAGMENT generated ID of the user - */ - id: string; - - /** - * External ID of the user - */ - external_id?: string; - } - } - } - - export interface DeleteAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - item: DeleteAllocationDiffEntry.Item; - - /** - * An allocation was deleted - */ - op: 'delete'; - } - - export namespace DeleteAllocationDiffEntry { - /** - * Transaction allocation against an invoice. - */ - export interface Item { - /** - * Allocated amount in smallest currency unit as stringified bigint. - */ - amount: string; - - /** - * The invoice this allocation is applied against. - */ - invoice_id: string; - - /** - * The type of allocation. - */ - type: 'invoice_payin' | 'invoice_payout'; - - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - user: Item.User; - } - - export namespace Item { - /** - * User reference in API responses: Fragment user id and optional external_id. - */ - export interface User { - /** - * FRAGMENT generated ID of the user - */ - id: string; - - /** - * External ID of the user - */ - external_id?: string; - } - } - } - - export interface UpdateAllocationDiffEntry { - /** - * The ID of the updated allocation. - */ - id: string; - - /** - * New amount in smallest currency unit as stringified bigint. - */ - new_amount: string; - - /** - * Previous amount in smallest currency unit as stringified bigint. - */ - old_amount: string; - + export namespace DataV2 { + /** + * Pagination cursors. + */ + export interface PageInfo { /** - * An allocation was updated + * Cursor to fetch the next page of results. */ - op: 'update'; + next_cursor?: string; } } } -/** - * Search results for transaction allocations. - */ export interface TransactionSearchAllocationsResponse { + /** + * List of allocation search results. + */ data: Array; } export namespace TransactionSearchAllocationsResponse { /** - * A flattened allocation with a reference to its parent transaction. + * An allocation with a reference to its parent transaction. */ export interface Data { /** - * Allocation ID. + * FRAGMENT generated unique ID. */ id: string; /** - * Allocated amount in smallest currency unit as stringified bigint. + * Allocated amount, as a positive string in the smallest currency unit, such as + * cents for USD. */ amount: string; /** - * The invoice this allocation is applied against. + * Invoice the allocation is applied against. */ invoice_id: string; /** - * Posted timestamp of the parent transaction in ISO 8601 format. + * Timestamp when the parent transaction was posted. Uses ISO 8601 format. */ posted: string; /** - * Reference to a transaction by encoded ID and external ID. + * Transaction the allocation is applied to. */ transaction: Data.Transaction; /** - * The type of allocation. + * Type of allocation. */ type: 'invoice_payin' | 'invoice_payout'; /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the allocation. */ user: Data.User; } export namespace Data { /** - * Reference to a transaction by encoded ID and external ID. + * Transaction the allocation is applied to. */ export interface Transaction { /** - * Encoded transaction ID. + * FRAGMENT generated unique ID. */ id: string; /** - * External transaction ID. + * User-provided unique ID. */ external_id: string; } /** - * User reference in API responses: Fragment user id and optional external_id. + * User associated with the allocation. */ export interface User { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; /** - * External ID of the user + * User-provided unique ID. */ - external_id?: string; + external_id: string; } } } export interface TransactionCreateParams { /** - * Account reference. Provide id, external_id, or both. + * External account for the transaction. Identify it by `id`, `external_id`, or + * both. */ account: TransactionCreateParams.Account; /** - * Allocation entries for this transaction. Empty indicates unreconciled funds. + * Allocations for the transaction. An empty array indicates unreconciled funds. */ allocations: Array; /** - * Amount in smallest currency unit as stringified bigint (can be positive or - * negative). + * Transaction amount, as a string in the smallest currency unit, such as cents for + * USD. Can be positive or negative. */ amount: string; /** - * Currency code (ISO 4217 or crypto) + * ISO 4217 or crypto currency code. */ currency: | 'ADA' @@ -1122,58 +807,60 @@ export interface TransactionCreateParams { | 'CUSTOM'; /** - * External transaction ID used for idempotent sync. + * User-provided unique ID. */ external_id: string; /** - * Posted timestamp in ISO 8601 format. + * Timestamp when the transaction was posted. Uses ISO 8601 format. */ posted: string; /** - * Optional metadata tags for this transaction + * Tags for the transaction. */ tags?: Array; } export namespace TransactionCreateParams { /** - * Account reference. Provide id, external_id, or both. + * External account for the transaction. Identify it by `id`, `external_id`, or + * both. */ export interface Account { /** - * User-facing encoded account ID. + * FRAGMENT generated unique ID. */ id?: string; /** - * External account reference ID. + * User-provided unique ID. */ external_id?: string; } /** - * Transaction allocation against an invoice. + * An allocation linking a transaction to an invoice. */ export interface Allocation { /** - * Amount to allocate in smallest currency unit as stringified bigint. + * Allocation amount, as a positive string in the smallest currency unit, such as + * cents for USD. */ amount: string; /** - * The invoice to allocate against. + * Invoice to allocate against. */ invoice_id: string; /** - * The type of allocation. + * Type of allocation. */ type: 'invoice_payin' | 'invoice_payout'; /** - * Identifies a user by Fragment-generated id or external_id (request body). + * Identifies a user by `id` or `external_id`. */ user: Allocation.ID | Allocation.ExternalID; } @@ -1181,32 +868,30 @@ export namespace TransactionCreateParams { export namespace Allocation { export interface ID { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; } export interface ExternalID { /** - * External ID of the user + * User-provided unique ID. */ external_id: string; } } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Tag { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -1214,50 +899,60 @@ export namespace TransactionCreateParams { export interface TransactionUpdateParams { /** - * Current transaction version for optimistic concurrency control. + * Current version of the transaction. Must match the stored version. */ current_transaction_version: number; + /** + * Allocation updates. + */ allocations?: TransactionUpdateParams.Allocations; + /** + * Tag updates. + */ tags?: TransactionUpdateParams.Tags; } export namespace TransactionUpdateParams { + /** + * Allocation updates. + */ export interface Allocations { /** - * Allocations to add to the transaction + * Allocations to create. */ create?: Array; /** - * Existing allocations to update + * Allocations to update. */ update?: Array; } export namespace Allocations { /** - * Transaction allocation against an invoice. + * An allocation linking a transaction to an invoice. */ export interface Create { /** - * Amount to allocate in smallest currency unit as stringified bigint. + * Allocation amount, as a positive string in the smallest currency unit, such as + * cents for USD. */ amount: string; /** - * The invoice to allocate against. + * Invoice to allocate against. */ invoice_id: string; /** - * The type of allocation. + * Type of allocation. */ type: 'invoice_payin' | 'invoice_payout'; /** - * Identifies a user by Fragment-generated id or external_id (request body). + * Identifies a user by `id` or `external_id`. */ user: Create.ID | Create.ExternalID; } @@ -1265,14 +960,14 @@ export namespace TransactionUpdateParams { export namespace Create { export interface ID { /** - * FRAGMENT generated ID of the user + * FRAGMENT generated unique ID. */ id: string; } export interface ExternalID { /** - * External ID of the user + * User-provided unique ID. */ external_id: string; } @@ -1280,72 +975,92 @@ export namespace TransactionUpdateParams { export interface Update { /** - * The ID of the allocation to update. + * Allocation to update. */ id: string; /** - * New amount in smallest currency unit as stringified bigint. + * Updated allocation amount, as a positive string in the smallest currency unit, + * such as cents for USD. */ amount: string; } } + /** + * Tag updates. + */ export interface Tags { /** - * Tags to add + * Tags to create. The tag key must not already exist. */ create?: Array; /** - * Tags to remove by key + * Tags to remove. */ delete?: Array; /** - * Tags to update. The key identifies the existing tag; the value is the new value. + * Tags to set. Creates a new tag or updates an existing tag. + */ + set?: Array; + + /** + * Tags to update. The tag key must already exist. */ update?: Array; } export namespace Tags { /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Create { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } export interface Delete { /** - * Tag key to delete + * Tag key to delete. + */ + key: string; + } + + /** + * A key-value tag pair for metadata. + */ + export interface Set { + /** + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; + + /** + * Tag value. Must not contain #, /, or :. Max 200 characters. + */ + value: string; } /** - * A key-value tag pair for metadata + * A key-value tag pair for metadata. */ export interface Update { /** - * Tag key. Must be a valid safe string (no special characters like #, /, :). Max - * 50 characters. + * Tag key. Must not contain #, /, or :. Max 50 characters. */ key: string; /** - * Tag value. Must be a valid safe string (no special characters like #, /, :). Max - * 200 characters. + * Tag value. Must not contain #, /, or :. Max 200 characters. */ value: string; } @@ -1354,154 +1069,172 @@ export namespace TransactionUpdateParams { export interface TransactionListParams { /** - * Filter by account. Encoded account ID (ext_account_xxx) or external_id. If the - * account does not exist, returns an empty list. + * Filter by account `id` or `external_id`. If the account does not exist, returns + * an empty list. */ account?: string; /** - * Filter by reconciliation state. reconciled = unallocated_amount === 0; - * unreconciled = unallocated_amount !== 0. Omit for all transactions. + * Filter by reconciliation status. `reconciled` returns transactions where + * unallocated_amount is 0. `unreconciled` returns transactions where + * unallocated_amount is not 0. Omit for all transactions. */ reconciliation_status?: 'reconciled' | 'unreconciled'; } -export interface TransactionCreateAllocationsParams { +export interface TransactionSearchParams { /** - * Allocation operations to apply + * Filter for searching transactions. */ - allocation_updates: Array< - | TransactionCreateAllocationsParams.AddAllocationOperation - | TransactionCreateAllocationsParams.DeleteAllocationOperation - >; + filter: TransactionSearchParams.Filter; /** - * Current transaction version for optimistic concurrency control + * Pagination parameters. */ - version: number; + page_info?: TransactionSearchParams.PageInfo; } -export namespace TransactionCreateAllocationsParams { +export namespace TransactionSearchParams { /** - * Transaction allocation against an invoice. + * Filter for searching transactions. */ - export interface AddAllocationOperation { - /** - * Amount to allocate in smallest currency unit as stringified bigint. - */ - amount: string; - - /** - * The invoice to allocate against. - */ - invoice_id: string; - + export interface Filter { /** - * Add a new allocation + * Account filter. */ - op: 'add'; + account?: Filter.Account; /** - * The type of allocation. + * Tag-based filter criteria. When both `any` and `all` are provided, results must + * match every entry in `all` AND at least one entry in `any`. */ - type: 'invoice_payin' | 'invoice_payout'; + tags?: Filter.Tags; + } + export namespace Filter { /** - * Identifies a user by Fragment-generated id or external_id (request body). + * Account filter. */ - user: AddAllocationOperation.ID | AddAllocationOperation.ExternalID; - } - - export namespace AddAllocationOperation { - export interface ID { + export interface Account { /** - * FRAGMENT generated ID of the user + * Match transactions belonging to any of these accounts, using OR logic. */ - id: string; + any: Array; } - export interface ExternalID { + export namespace Account { /** - * External ID of the user + * External account for the transaction. Identify it by `id`, `external_id`, or + * both. */ - external_id: string; - } - } + export interface Any { + /** + * FRAGMENT generated unique ID. + */ + id?: string; - export interface DeleteAllocationOperation { - /** - * The ID of the allocation to remove. - */ - id: string; + /** + * User-provided unique ID. + */ + external_id?: string; + } + } /** - * Delete an allocation + * Tag-based filter criteria. When both `any` and `all` are provided, results must + * match every entry in `all` AND at least one entry in `any`. */ - op: 'delete'; - } -} - -export interface TransactionSearchParams { - /** - * Filter criteria for searching transactions. - */ - filter: TransactionSearchParams.Filter; -} - -export namespace TransactionSearchParams { - /** - * Filter criteria for searching transactions. - */ - export interface Filter { - account: Filter.Account; - } + export interface Tags { + /** + * Returns transactions matching every specified tag, using AND logic. + */ + all?: Array; - export namespace Filter { - export interface Account { /** - * Match transactions belonging to any of these accounts (OR). + * Returns transactions matching at least one of the specified tags, using OR + * logic. */ - any: Array; + any?: Array; } - export namespace Account { + export namespace Tags { + /** + * A tag filter. + */ + export interface All { + /** + * Tag key to filter on. Must be an exact match; wildcards are not supported. + */ + key: string; + + /** + * Tag value pattern to filter on. Supports wildcards: `*` matches any characters, + * `?` matches a single character. Use `\*` or `\?` to match literal asterisks or + * question marks. Use `*` to match any value for the given key. + */ + value: string; + } + /** - * Account reference. Provide id, external_id, or both. + * A tag filter. */ export interface Any { /** - * User-facing encoded account ID. + * Tag key to filter on. Must be an exact match; wildcards are not supported. */ - id?: string; + key: string; /** - * External account reference ID. + * Tag value pattern to filter on. Supports wildcards: `*` matches any characters, + * `?` matches a single character. Use `\*` or `\?` to match literal asterisks or + * question marks. Use `*` to match any value for the given key. */ - external_id?: string; + value: string; } } } + + /** + * Pagination parameters. + */ + export interface PageInfo { + /** + * Cursor for fetching the next page of results. + */ + after?: string; + + /** + * Number of results to return. Defaults to 20. + */ + limit?: number; + } } export interface TransactionSearchAllocationsParams { /** - * Filter criteria for searching transaction allocations. + * Filter for searching transaction allocations. */ filter: TransactionSearchAllocationsParams.Filter; } export namespace TransactionSearchAllocationsParams { /** - * Filter criteria for searching transaction allocations. + * Filter for searching transaction allocations. */ export interface Filter { + /** + * Invoice ID filter. + */ invoice_id: Filter.InvoiceID; } export namespace Filter { + /** + * Invoice ID filter. + */ export interface InvoiceID { /** - * Match allocations where invoice_id is any of these values (OR). + * Match allocations where invoice_id is any of these values, using OR logic. */ any: Array; } @@ -1515,14 +1248,12 @@ export declare namespace Transactions { type TransactionRetrieveResponse as TransactionRetrieveResponse, type TransactionUpdateResponse as TransactionUpdateResponse, type TransactionListResponse as TransactionListResponse, - type TransactionCreateAllocationsResponse as TransactionCreateAllocationsResponse, type TransactionListHistoryResponse as TransactionListHistoryResponse, type TransactionSearchResponse as TransactionSearchResponse, type TransactionSearchAllocationsResponse as TransactionSearchAllocationsResponse, type TransactionCreateParams as TransactionCreateParams, type TransactionUpdateParams as TransactionUpdateParams, type TransactionListParams as TransactionListParams, - type TransactionCreateAllocationsParams as TransactionCreateAllocationsParams, type TransactionSearchParams as TransactionSearchParams, type TransactionSearchAllocationsParams as TransactionSearchAllocationsParams, }; diff --git a/src/resources/users.ts b/src/resources/users.ts index bff0394..bfc83f3 100644 --- a/src/resources/users.ts +++ b/src/resources/users.ts @@ -4,9 +4,12 @@ import { APIResource } from '../core/resource'; import { APIPromise } from '../core/api-promise'; import { RequestOptions } from '../internal/request-options'; +/** + * User management operations + */ export class Users extends APIResource { /** - * Creates a new user + * Creates a user. * * @example * ```ts @@ -21,7 +24,7 @@ export class Users extends APIResource { } /** - * Lists all users for the workspace + * Lists all users. * * @example * ```ts @@ -34,47 +37,50 @@ export class Users extends APIResource { } /** - * User object + * User object. */ export interface User { /** - * Unique user ID + * FRAGMENT generated unique ID. */ id: string; /** - * External ID for the user + * User-provided unique ID. */ external_id: string; /** - * Role of the user + * Name of the user's role. */ role: string; } export interface UserCreateResponse { /** - * User object + * User object. */ data: User; } /** - * List of users + * List of users. */ export interface UserListResponse { + /** + * List of users. + */ data: Array; } export interface UserCreateParams { /** - * External ID for the user + * User-provided unique ID. */ external_id: string; /** - * Role of the user + * Name of the role to assign. Must match an existing role. */ role: string; } diff --git a/src/version.ts b/src/version.ts index b4e51da..bc95435 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.20.0'; // x-release-please-version +export const VERSION = '0.21.0'; // x-release-please-version diff --git a/tests/api-resources/invoices.test.ts b/tests/api-resources/invoices.test.ts index 7cfbe6c..0200c27 100644 --- a/tests/api-resources/invoices.test.ts +++ b/tests/api-resources/invoices.test.ts @@ -48,10 +48,10 @@ describe('resource invoices', () => { quantity: 2, unit_price: '500', }, - tags: [{ key: 'region', value: 'us-east' }], + tags: [{ key: 'department', value: 'engineering' }], }, ], - tags: [{ key: 'region', value: 'us-east' }], + tags: [{ key: 'department', value: 'engineering' }], }); }); @@ -97,7 +97,7 @@ describe('resource invoices', () => { quantity: 2, unit_price: '500', }, - tags: [{ key: 'region', value: 'us-east' }], + tags: [{ key: 'department', value: 'engineering' }], }, ], delete: [{ id: 'id' }], @@ -111,17 +111,19 @@ describe('resource invoices', () => { amount: '2000', }, tags: { - create: [{ key: 'region', value: 'us-east' }], + create: [{ key: 'department', value: 'engineering' }], delete: [{ key: 'key' }], - update: [{ key: 'region', value: 'eu-west-1' }], + set: [{ key: 'department', value: 'engineering' }], + update: [{ key: 'department', value: 'engineering' }], }, }, ], }, tags: { - create: [{ key: 'region', value: 'us-east' }], + create: [{ key: 'department', value: 'engineering' }], delete: [{ key: 'key' }], - update: [{ key: 'region', value: 'eu-west-1' }], + set: [{ key: 'department', value: 'engineering' }], + update: [{ key: 'department', value: 'engineering' }], }, }); }); @@ -152,10 +154,7 @@ describe('resource invoices', () => { // Mock server tests are disabled test.skip('search: only required params', async () => { - const responsePromise = client.invoices.search({ - filter: {}, - page_info: {}, - }); + const responsePromise = client.invoices.search({ filter: {} }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -170,7 +169,10 @@ describe('resource invoices', () => { const response = await client.invoices.search({ filter: { status: 'open', - tags: { all: [{ key: 'env', value: 'prod' }], any: [{ key: 'region', value: 'us-*' }] }, + tags: { + all: [{ key: 'department', value: 'engineering' }], + any: [{ key: 'department', value: 'eng*' }], + }, }, page_info: { after: 'after', limit: 20 }, }); diff --git a/tests/api-resources/transactions.test.ts b/tests/api-resources/transactions.test.ts index 9286478..98d3e67 100644 --- a/tests/api-resources/transactions.test.ts +++ b/tests/api-resources/transactions.test.ts @@ -24,7 +24,7 @@ describe('resource transactions', () => { amount: '-1000', currency: 'USD', external_id: 'bank_txn_123', - posted: '2026-02-12T00:00:00.000Z', + posted: '2024-01-13T00:00:00Z', }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); @@ -50,8 +50,8 @@ describe('resource transactions', () => { amount: '-1000', currency: 'USD', external_id: 'bank_txn_123', - posted: '2026-02-12T00:00:00.000Z', - tags: [{ key: 'region', value: 'us-east' }], + posted: '2024-01-13T00:00:00Z', + tags: [{ key: 'department', value: 'engineering' }], }); }); @@ -95,9 +95,10 @@ describe('resource transactions', () => { update: [{ id: 'alloc_abc123', amount: '2000' }], }, tags: { - create: [{ key: 'region', value: 'us-east' }], + create: [{ key: 'department', value: 'engineering' }], delete: [{ key: 'key' }], - update: [{ key: 'region', value: 'eu-west-1' }], + set: [{ key: 'department', value: 'engineering' }], + update: [{ key: 'department', value: 'engineering' }], }, }); }); @@ -125,45 +126,6 @@ describe('resource transactions', () => { ).rejects.toThrow(Fragment.NotFoundError); }); - // Mock server tests are disabled - test.skip('createAllocations: only required params', async () => { - const responsePromise = client.transactions.createAllocations('txn_abc123', { - allocation_updates: [ - { - amount: '1000', - invoice_id: 'inv_abc123', - op: 'add', - type: 'invoice_payin', - user: { id: 'user_abc123' }, - }, - ], - version: 0, - }); - const rawResponse = await responsePromise.asResponse(); - expect(rawResponse).toBeInstanceOf(Response); - const response = await responsePromise; - expect(response).not.toBeInstanceOf(Response); - const dataAndResponse = await responsePromise.withResponse(); - expect(dataAndResponse.data).toBe(response); - expect(dataAndResponse.response).toBe(rawResponse); - }); - - // Mock server tests are disabled - test.skip('createAllocations: required and optional params', async () => { - const response = await client.transactions.createAllocations('txn_abc123', { - allocation_updates: [ - { - amount: '1000', - invoice_id: 'inv_abc123', - op: 'add', - type: 'invoice_payin', - user: { id: 'user_abc123' }, - }, - ], - version: 0, - }); - }); - // Mock server tests are disabled test.skip('listHistory', async () => { const responsePromise = client.transactions.listHistory('txn_abc123'); @@ -178,7 +140,7 @@ describe('resource transactions', () => { // Mock server tests are disabled test.skip('search: only required params', async () => { - const responsePromise = client.transactions.search({ filter: { account: { any: [{}] } } }); + const responsePromise = client.transactions.search({ filter: {} }); const rawResponse = await responsePromise.asResponse(); expect(rawResponse).toBeInstanceOf(Response); const response = await responsePromise; @@ -191,7 +153,14 @@ describe('resource transactions', () => { // Mock server tests are disabled test.skip('search: required and optional params', async () => { const response = await client.transactions.search({ - filter: { account: { any: [{ id: 'ext_account_YWJjMTIz', external_id: 'acct_external_123' }] } }, + filter: { + account: { any: [{ id: 'ext_account_YWJjMTIz', external_id: 'acct_external_123' }] }, + tags: { + all: [{ key: 'department', value: 'engineering' }], + any: [{ key: 'department', value: 'eng*' }], + }, + }, + page_info: { after: 'after', limit: 20 }, }); });