@lightsparkdev/grid 0.2.1

package/src/resources/exchange-rates.ts

@@ -0,0 +1,127 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as QuotesAPI from './quotes';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class ExchangeRates extends APIResource {
+  /**
+   * Retrieve cached exchange rates for currency corridors. Returns FX rates that are
+   * cached for approximately 5 minutes. Rates include fees specific to your platform
+   * for authenticated requests.
+   *
+   * **Filtering Options:**
+   *
+   * - Filter by source currency to get all available destination corridors
+   * - Filter by specific destination currency or currencies
+   * - Provide a sending amount to get calculated receiving amounts
+   */
+  list(
+    query: ExchangeRateListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExchangeRateListResponse> {
+    return this._client.get('/exchange-rates', { query, ...options });
+  }
+}
+
+export interface ExchangeRateListResponse {
+  /**
+   * List of exchange rates matching the filter criteria
+   */
+  data: Array<ExchangeRateListResponse.Data>;
+}
+
+export namespace ExchangeRateListResponse {
+  /**
+   * Exchange rate information for a currency corridor
+   */
+  export interface Data {
+    destinationCurrency: QuotesAPI.Currency;
+
+    /**
+     * The payment rail used for the destination (e.g., UPI, SEPA_INSTANT,
+     * MOBILE_MONEY, FASTER_PAYMENTS)
+     */
+    destinationPaymentRail: string;
+
+    /**
+     * Number of sending currency units per receiving currency unit.
+     */
+    exchangeRate: number;
+
+    /**
+     * Fees associated with an exchange rate
+     */
+    fees: Data.Fees;
+
+    /**
+     * The maximum supported sending amount in the smallest unit of the source
+     * currency.
+     */
+    maxSendingAmount: number;
+
+    /**
+     * The minimum supported sending amount in the smallest unit of the source
+     * currency.
+     */
+    minSendingAmount: number;
+
+    /**
+     * The receiving amount in the smallest unit of the destination currency
+     */
+    receivingAmount: number;
+
+    /**
+     * The sending amount in the smallest unit of the source currency (e.g., cents for
+     * USD). Echoed back from the request if provided.
+     */
+    sendingAmount: number;
+
+    sourceCurrency: QuotesAPI.Currency;
+
+    /**
+     * Timestamp when this exchange rate was last refreshed
+     */
+    updatedAt: string;
+  }
+
+  export namespace Data {
+    /**
+     * Fees associated with an exchange rate
+     */
+    export interface Fees {
+      /**
+       * Fixed fee in the smallest unit of the sending currency (e.g., cents for USD)
+       */
+      fixed?: number;
+    }
+  }
+}
+
+export interface ExchangeRateListParams {
+  /**
+   * Filter by destination currency code(s). Can be repeated for multiple currencies
+   * (e.g., &destinationCurrency=INR&destinationCurrency=GBP)
+   */
+  destinationCurrency?: Array<string>;
+
+  /**
+   * Sending amount in the smallest unit of the source currency (e.g., cents for
+   * USD). If no amount is provided, the default is 10000 in the sending currency
+   * smallest unit.
+   */
+  sendingAmount?: number;
+
+  /**
+   * Filter by source currency code (e.g., USD)
+   */
+  sourceCurrency?: string;
+}
+
+export declare namespace ExchangeRates {
+  export {
+    type ExchangeRateListResponse as ExchangeRateListResponse,
+    type ExchangeRateListParams as ExchangeRateListParams,
+  };
+}

package/src/resources/index.ts

@@ -0,0 +1,104 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Config,
+  type CustomerInfoFieldName,
+  type PlatformConfig,
+  type PlatformCurrencyConfig,
+  type ConfigUpdateParams,
+} from './config';
+export {
+  Customers,
+  type Customer,
+  type CustomerCreate,
+  type CustomerOneOf,
+  type CustomerUpdate,
+  type CustomerRetrieveResponse,
+  type CustomerUpdateResponse,
+  type CustomerDeleteResponse,
+  type CustomerGetKYCLinkResponse,
+  type CustomerCreateParams,
+  type CustomerUpdateParams,
+  type CustomerListParams,
+  type CustomerGetKYCLinkParams,
+  type CustomerListInternalAccountsParams,
+  type CustomerOneovesDefaultPagination,
+} from './customers/customers';
+export { ExchangeRates, type ExchangeRateListResponse, type ExchangeRateListParams } from './exchange-rates';
+export {
+  Invitations,
+  type CurrencyAmount,
+  type UmaInvitation,
+  type InvitationCreateParams,
+  type InvitationClaimParams,
+} from './invitations';
+export {
+  Plaid,
+  type PlaidCreateLinkTokenResponse,
+  type PlaidCreateLinkTokenParams,
+  type PlaidSubmitPublicTokenParams,
+} from './plaid';
+export {
+  Platform,
+  type PlatformListInternalAccountsResponse,
+  type PlatformListInternalAccountsParams,
+} from './platform/platform';
+export {
+  Quotes,
+  type BaseDestination,
+  type BasePaymentAccountInfo,
+  type BaseQuoteSource,
+  type Currency,
+  type OutgoingRateDetails,
+  type PaymentInstructions,
+  type Quote,
+  type QuoteDestinationOneOf,
+  type QuoteSourceOneOf,
+  type QuoteCreateParams,
+  type QuoteListParams,
+  type QuotesDefaultPagination,
+} from './quotes';
+export {
+  Receiver,
+  type CounterpartyFieldDefinition,
+  type LookupResponse,
+  type ReceiverLookupExternalAccountResponse,
+  type ReceiverLookupUmaResponse,
+  type ReceiverLookupExternalAccountParams,
+  type ReceiverLookupUmaParams,
+} from './receiver';
+export { Sandbox, type SandboxSendFundsResponse, type SandboxSendFundsParams } from './sandbox/sandbox';
+export {
+  Tokens,
+  type APIToken,
+  type Permission,
+  type TokenCreateParams,
+  type TokenListParams,
+  type APITokensDefaultPagination,
+} from './tokens';
+export {
+  Transactions,
+  type BaseTransactionSource,
+  type IncomingTransaction,
+  type TransactionSourceOneOf,
+  type TransactionStatus,
+  type TransactionType,
+  type TransactionListParams,
+  type TransactionApproveParams,
+  type TransactionRejectParams,
+} from './transactions';
+export {
+  TransferIn,
+  type BaseTransactionDestination,
+  type Transaction,
+  type TransferInCreateParams,
+  type TransactionsDefaultPagination,
+} from './transfer-in';
+export { TransferOut, type TransferOutCreateParams } from './transfer-out';
+export {
+  UmaProviders,
+  type UmaProviderListResponse,
+  type UmaProviderListParams,
+  type UmaProviderListResponsesDefaultPagination,
+} from './uma-providers';
+export { Webhooks, type WebhookSendTestResponse } from './webhooks';

package/src/resources/invitations.ts

@@ -0,0 +1,207 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as QuotesAPI from './quotes';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Invitations extends APIResource {
+  /**
+   * Create an UMA invitation from a given platform customer.
+   *
+   * @example
+   * ```ts
+   * const umaInvitation = await client.invitations.create({
+   *   inviterUma: '$inviter@uma.domain',
+   * });
+   * ```
+   */
+  create(body: InvitationCreateParams, options?: RequestOptions): APIPromise<UmaInvitation> {
+    return this._client.post('/invitations', { body, ...options });
+  }
+
+  /**
+   * Retrieve details about an UMA invitation by its invitation code.
+   *
+   * @example
+   * ```ts
+   * const umaInvitation = await client.invitations.retrieve(
+   *   'invitationCode',
+   * );
+   * ```
+   */
+  retrieve(invitationCode: string, options?: RequestOptions): APIPromise<UmaInvitation> {
+    return this._client.get(path`/invitations/${invitationCode}`, options);
+  }
+
+  /**
+   * Cancel a pending UMA invitation. Only the inviter or platform can cancel an
+   * invitation.
+   *
+   * When an invitation is cancelled:
+   *
+   * 1. The invitation status changes from PENDING to CANCELLED
+   * 2. The invitation can no longer be claimed
+   * 3. The invitation URL will show as cancelled when accessed
+   *
+   * Only pending invitations can be cancelled. Attempting to cancel an invitation
+   * that is already claimed, expired, or cancelled will result in an error.
+   *
+   * @example
+   * ```ts
+   * const umaInvitation = await client.invitations.cancel(
+   *   'invitationCode',
+   * );
+   * ```
+   */
+  cancel(invitationCode: string, options?: RequestOptions): APIPromise<UmaInvitation> {
+    return this._client.post(path`/invitations/${invitationCode}/cancel`, options);
+  }
+
+  /**
+   * Claim an UMA invitation by associating it with an invitee UMA address.
+   *
+   * When an invitation is successfully claimed:
+   *
+   * 1. The invitation status changes from PENDING to CLAIMED
+   * 2. The invitee UMA address is associated with the invitation
+   * 3. An INVITATION_CLAIMED webhook is triggered to notify the platform that
+   *    created the invitation
+   *
+   * This endpoint allows customers to accept invitations sent to them by other UMA
+   * customers.
+   *
+   * @example
+   * ```ts
+   * const umaInvitation = await client.invitations.claim(
+   *   'invitationCode',
+   *   { inviteeUma: '$invitee@uma.domain' },
+   * );
+   * ```
+   */
+  claim(
+    invitationCode: string,
+    body: InvitationClaimParams,
+    options?: RequestOptions,
+  ): APIPromise<UmaInvitation> {
+    return this._client.post(path`/invitations/${invitationCode}/claim`, { body, ...options });
+  }
+}
+
+export interface CurrencyAmount {
+  /**
+   * Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis
+   * for BTC)
+   */
+  amount: number;
+
+  currency: QuotesAPI.Currency;
+}
+
+export interface UmaInvitation {
+  /**
+   * The unique code of the invitation
+   */
+  code: string;
+
+  /**
+   * When the invitation was created
+   */
+  createdAt: string;
+
+  /**
+   * The UMA address of the inviter
+   */
+  inviterUma: string;
+
+  /**
+   * The status of the invitation
+   */
+  status: 'PENDING' | 'CLAIMED' | 'EXPIRED' | 'CANCELLED';
+
+  /**
+   * The URL where this invitation can be claimed.
+   */
+  url: string;
+
+  /**
+   * The amount to send to the invitee when the invitation is claimed. This is
+   * optional and if not provided, the invitee will not receive any amount. Note that
+   * the actual sending of the amount must be done by the inviter platform once the
+   * INVITATION_CLAIMED webhook is received. If the inviter platform either does not
+   * send the payment or the payment fails, the invitee will not receive this amount.
+   * This field is primarily used for display purposes on the claiming side of the
+   * invitation. This field is useful for "send-by-link" style customer flows where
+   * an inviter can send a payment simply by sharing a link without knowing the
+   * receiver's UMA address. Note that these sends can only be sender-locked, meaning
+   * that the sender will not know ahead of time how much the receiver will receive
+   * in the receiving currency.
+   */
+  amountToSend?: CurrencyAmount;
+
+  /**
+   * When the invitation was claimed if it has been claimed
+   */
+  claimedAt?: string;
+
+  /**
+   * When the invitation expires (if at all)
+   */
+  expiresAt?: string;
+
+  /**
+   * The inviter's first name. Will be displayed when the recipient clicks the invite
+   * link
+   */
+  firstName?: string;
+
+  /**
+   * The UMA address of the invitee
+   */
+  inviteeUma?: string;
+}
+
+export interface InvitationCreateParams {
+  /**
+   * The UMA address of the customer creating the invitation
+   */
+  inviterUma: string;
+
+  /**
+   * An amount to send (in the smallest unit of the customer's currency) to the
+   * invitee when the invitation is claimed. This is optional and if not provided,
+   * the invitee will not receive any amount. Note that the actual sending of the
+   * amount must be done by the inviter platform once the INVITATION_CLAIMED webhook
+   * is received. If the inviter platform either does not send the payment or the
+   * payment fails, the invitee will not receive this amount. This field is primarily
+   * used for display purposes on the claiming side of the invitation.
+   */
+  amountToSend?: number;
+
+  /**
+   * When the invitation expires (if at all)
+   */
+  expiresAt?: string;
+
+  /**
+   * First name of the invitee to show as part of the invite
+   */
+  firstName?: string;
+}
+
+export interface InvitationClaimParams {
+  /**
+   * The UMA address of the customer claiming the invitation
+   */
+  inviteeUma: string;
+}
+
+export declare namespace Invitations {
+  export {
+    type CurrencyAmount as CurrencyAmount,
+    type UmaInvitation as UmaInvitation,
+    type InvitationCreateParams as InvitationCreateParams,
+    type InvitationClaimParams as InvitationClaimParams,
+  };
+}

package/src/resources/plaid.ts

@@ -0,0 +1,128 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as ExternalAccountsAPI from './customers/external-accounts';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Plaid extends APIResource {
+  /**
+   * Creates a Plaid Link token that can be used to initialize Plaid Link in your
+   * application. The Link token is used to authenticate the customer and allow them
+   * to select their bank account.
+   *
+   * **Async Flow:**
+   *
+   * 1. Platform calls this endpoint to get a link_token and callbackUrl
+   * 2. Platform displays Plaid Link UI to the end customer using the link_token
+   * 3. End customer authenticates with their bank and selects an account
+   * 4. Plaid returns a public_token to the platform
+   * 5. Platform POSTs the public_token to the callbackUrl
+   * 6. Lightspark exchanges the public_token with Plaid and creates the external
+   *    account asynchronously
+   * 7. Platform receives a webhook notification when the external account is ready
+   *
+   * @example
+   * ```ts
+   * const response = await client.plaid.createLinkToken({
+   *   customerId:
+   *     'Customer:019542f5-b3e7-1d02-0000-000000000001',
+   * });
+   * ```
+   */
+  createLinkToken(
+    body: PlaidCreateLinkTokenParams,
+    options?: RequestOptions,
+  ): APIPromise<PlaidCreateLinkTokenResponse> {
+    return this._client.post('/plaid/link-tokens', { body, ...options });
+  }
+
+  /**
+   * After the customer completes Plaid Link authentication, the platform should POST
+   * the public_token to this callback URL (provided in the link token response).
+   *
+   * This will trigger asynchronous processing:
+   *
+   * 1. Lightspark exchanges the public_token for an access_token with Plaid
+   * 2. Lightspark retrieves and verifies the account details
+   * 3. An external account is created
+   * 4. A webhook notification is sent to the platform when complete
+   *
+   * @example
+   * ```ts
+   * const externalAccount =
+   *   await client.plaid.submitPublicToken(
+   *     'link-sandbox-abc123xyz-1234-5678',
+   *     {
+   *       publicToken:
+   *         'public-sandbox-12345678-1234-1234-1234-123456789012',
+   *       accountId: 'plaid_account_id_123',
+   *     },
+   *   );
+   * ```
+   */
+  submitPublicToken(
+    plaidLinkToken: string,
+    body: PlaidSubmitPublicTokenParams,
+    options?: RequestOptions,
+  ): APIPromise<ExternalAccountsAPI.ExternalAccount> {
+    return this._client.post(path`/plaid/callback/${plaidLinkToken}`, { body, ...options });
+  }
+}
+
+export interface PlaidCreateLinkTokenResponse {
+  /**
+   * The URL where the platform should POST the public_token after the customer
+   * completes Plaid Link authentication. This will trigger asynchronous external
+   * account creation. The URL includes the linkToken as the path parameter.
+   */
+  callbackUrl: string;
+
+  /**
+   * The ISO 8601 timestamp when this link token expires. Link tokens typically
+   * expire after 4 hours.
+   */
+  expiration: string;
+
+  /**
+   * The Plaid Link token to be used to initialize Plaid Link in your application.
+   * This token is single-use and expires after the specified expiration time.
+   */
+  linkToken: string;
+
+  /**
+   * A unique identifier for this request, useful for debugging
+   */
+  requestId?: string;
+}
+
+export interface PlaidCreateLinkTokenParams {
+  /**
+   * The ID of the customer for whom to create the Plaid Link token and external
+   * account
+   */
+  customerId: string;
+}
+
+export interface PlaidSubmitPublicTokenParams {
+  /**
+   * The public token returned by Plaid Link after the customer successfully
+   * authenticates and selects an account.
+   */
+  publicToken: string;
+
+  /**
+   * Optional Plaid account ID if the customer selected a specific account. If not
+   * provided, the default account will be used.
+   */
+  accountId?: string;
+}
+
+export declare namespace Plaid {
+  export {
+    type PlaidCreateLinkTokenResponse as PlaidCreateLinkTokenResponse,
+    type PlaidCreateLinkTokenParams as PlaidCreateLinkTokenParams,
+    type PlaidSubmitPublicTokenParams as PlaidSubmitPublicTokenParams,
+  };
+}

package/src/resources/platform/external-accounts.ts

@@ -0,0 +1,136 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ExternalAccountsAPI from '../customers/external-accounts';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+export class ExternalAccounts extends APIResource {
+  /**
+   * Register a new external bank account for the platform.
+   *
+   * **Sandbox Testing:** In sandbox mode, use these account number patterns to test
+   * different transfer scenarios. These patterns should be used with the primary
+   * alias, address, or identifier of whatever account type you're testing. For
+   * example, the US account number, a CLABE, an IBAN, a spark wallet address, etc.
+   * The failure patterns are:
+   *
+   * - Account numbers ending in **002**: Insufficient funds (transfer-in will fail)
+   * - Account numbers ending in **003**: Account closed/invalid (transfers will
+   *   fail)
+   * - Account numbers ending in **004**: Transfer rejected (bank rejects the
+   *   transfer)
+   * - Account numbers ending in **005**: Timeout/delayed failure (stays pending
+   *   ~30s, then fails)
+   * - Any other account number: Success (transfers complete normally)
+   *
+   * @example
+   * ```ts
+   * const externalAccount =
+   *   await client.platform.externalAccounts.create({
+   *     accountInfo: {
+   *       accountType: 'US_ACCOUNT',
+   *       accountNumber: '12345678901',
+   *       routingNumber: '123456789',
+   *       accountCategory: 'CHECKING',
+   *       bankName: 'Chase Bank',
+   *       beneficiary: {
+   *         beneficiaryType: 'INDIVIDUAL',
+   *         fullName: 'John Doe',
+   *         birthDate: '1990-01-15',
+   *         nationality: 'US',
+   *         address: {
+   *           line1: '123 Main Street',
+   *           city: 'San Francisco',
+   *           state: 'CA',
+   *           postalCode: '94105',
+   *           country: 'US',
+   *         },
+   *       },
+   *     },
+   *     currency: 'USD',
+   *   });
+   * ```
+   */
+  create(
+    body: ExternalAccountCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<ExternalAccountsAPI.ExternalAccount> {
+    return this._client.post('/platform/external-accounts', { body, ...options });
+  }
+
+  /**
+   * Retrieve a list of all external accounts that belong to the platform, as opposed
+   * to an individual customer.
+   *
+   * These accounts are used for platform-wide operations such as receiving funds
+   * from external sources or managing platform-level payment destinations.
+   *
+   * @example
+   * ```ts
+   * const externalAccounts =
+   *   await client.platform.externalAccounts.list();
+   * ```
+   */
+  list(
+    query: ExternalAccountListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExternalAccountListResponse> {
+    return this._client.get('/platform/external-accounts', { query, ...options });
+  }
+}
+
+export interface ExternalAccountListResponse {
+  /**
+   * List of external accounts matching the filter criteria
+   */
+  data: Array<ExternalAccountsAPI.ExternalAccount>;
+}
+
+export interface ExternalAccountCreateParams {
+  accountInfo: ExternalAccountsAPI.ExternalAccountInfoOneOf;
+
+  /**
+   * The ISO 4217 currency code
+   */
+  currency: string;
+
+  /**
+   * The ID of the customer for whom to create the external account. If not provided,
+   * the external account will be created on behalf of the platform.
+   */
+  customerId?: string;
+
+  /**
+   * Whether to set the external account as the default UMA deposit account. When set
+   * to true, incoming payments to this customer's UMA address will be automatically
+   * deposited into this external account. False if not provided. Note that only one
+   * external account can be set as the default UMA deposit account for a customer,
+   * so if there is already a default UMA deposit account, this will override the
+   * existing default UMA deposit account. If there is no default UMA deposit
+   * account, incoming UMA payments will be deposited into the primary internal
+   * account for the customer.
+   */
+  defaultUmaDepositAccount?: boolean;
+
+  /**
+   * Your platform's identifier for the account in your system. This can be used to
+   * reference the account by your own identifier.
+   */
+  platformAccountId?: string;
+}
+
+export interface ExternalAccountListParams {
+  /**
+   * Filter by currency code
+   */
+  currency?: string;
+}
+
+export declare namespace ExternalAccounts {
+  export {
+    type ExternalAccountListResponse as ExternalAccountListResponse,
+    type ExternalAccountCreateParams as ExternalAccountCreateParams,
+    type ExternalAccountListParams as ExternalAccountListParams,
+  };
+}