@lightsparkdev/grid 0.2.1

package/src/resources/transactions.ts

@@ -0,0 +1,312 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as TransactionsAPI from './transactions';
+import * as InvitationsAPI from './invitations';
+import * as TransferInAPI from './transfer-in';
+import { TransactionsDefaultPagination } from './transfer-in';
+import { APIPromise } from '../core/api-promise';
+import { DefaultPagination, type DefaultPaginationParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Transactions extends APIResource {
+  /**
+   * Retrieve detailed information about a specific transaction.
+   *
+   * @example
+   * ```ts
+   * const transaction = await client.transactions.retrieve(
+   *   'transactionId',
+   * );
+   * ```
+   */
+  retrieve(transactionID: string, options?: RequestOptions): APIPromise<TransferInAPI.Transaction> {
+    return this._client.get(path`/transactions/${transactionID}`, options);
+  }
+
+  /**
+   * Retrieve a paginated list of transactions with optional filtering. The
+   * transactions can be filtered by customer ID, platform customer ID, UMA address,
+   * date range, status, and transaction type.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const transaction of client.transactions.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: TransactionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TransactionsDefaultPagination, TransferInAPI.Transaction> {
+    return this._client.getAPIList('/transactions', DefaultPagination<TransferInAPI.Transaction>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Approve a pending incoming payment that was previously acknowledged with a 202
+   * response. This endpoint allows platforms to asynchronously approve payments
+   * after async processing.
+   *
+   * @example
+   * ```ts
+   * const incomingTransaction =
+   *   await client.transactions.approve('transactionId');
+   * ```
+   */
+  approve(
+    transactionID: string,
+    body: TransactionApproveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<IncomingTransaction> {
+    return this._client.post(path`/transactions/${transactionID}/approve`, { body, ...options });
+  }
+
+  /**
+   * Reject a pending incoming payment that was previously acknowledged with a 202
+   * response. This endpoint allows platforms to asynchronously reject payments after
+   * additional processing.
+   *
+   * @example
+   * ```ts
+   * const incomingTransaction =
+   *   await client.transactions.reject('transactionId');
+   * ```
+   */
+  reject(
+    transactionID: string,
+    body: TransactionRejectParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<IncomingTransaction> {
+    return this._client.post(path`/transactions/${transactionID}/reject`, { body, ...options });
+  }
+}
+
+export interface BaseTransactionSource {
+  /**
+   * Currency code for the source
+   */
+  currency?: string;
+}
+
+export interface IncomingTransaction extends TransferInAPI.Transaction {
+  /**
+   * Amount received in the recipient's currency
+   */
+  receivedAmount: InvitationsAPI.CurrencyAmount;
+
+  /**
+   * If the transaction failed, this field provides the reason for failure.
+   */
+  failureReason?:
+    | 'LNURLP_FAILED'
+    | 'PAY_REQUEST_FAILED'
+    | 'PAYMENT_APPROVAL_WEBHOOK_ERROR'
+    | 'PAYMENT_APPROVAL_TIMED_OUT'
+    | 'OFFRAMP_FAILED'
+    | 'MISSING_MANDATORY_PAYEE_DATA'
+    | 'QUOTE_EXPIRED'
+    | 'QUOTE_EXECUTION_FAILED';
+
+  /**
+   * Details about the rate and fees for the transaction.
+   */
+  rateDetails?: IncomingTransaction.RateDetails;
+
+  /**
+   * Included for all transactions except those with "CREATED" status
+   */
+  reconciliationInstructions?: IncomingTransaction.ReconciliationInstructions;
+
+  /**
+   * Source account details
+   */
+  source?: TransactionSourceOneOf;
+}
+
+export namespace IncomingTransaction {
+  /**
+   * Details about the rate and fees for the transaction.
+   */
+  export interface RateDetails {
+    /**
+     * The fixed fee charged by the Grid product to execute the quote in the smallest
+     * unit of the receiving currency (eg. cents).
+     */
+    gridApiFixedFee: number;
+
+    /**
+     * The underlying multiplier from the mSATS to the receiving currency, including
+     * variable fees.
+     */
+    gridApiMultiplier: number;
+
+    /**
+     * The variable fee amount charged by the Grid product to execute the quote in the
+     * smallest unit of the receiving currency (eg. cents). This is the receiving
+     * amount times gridApiVariableFeeRate.
+     */
+    gridApiVariableFeeAmount: number;
+
+    /**
+     * The variable fee rate charged by the Grid product to execute the quote as a
+     * percentage of the receiving currency amount.
+     */
+    gridApiVariableFeeRate: number;
+  }
+
+  /**
+   * Included for all transactions except those with "CREATED" status
+   */
+  export interface ReconciliationInstructions {
+    /**
+     * Unique reference code that must be included with the payment to match it with
+     * the correct incoming transaction
+     */
+    reference: string;
+  }
+}
+
+/**
+ * Source account details
+ */
+export type TransactionSourceOneOf =
+  | TransactionSourceOneOf.AccountTransactionSource
+  | TransactionSourceOneOf.UmaAddressTransactionSource;
+
+export namespace TransactionSourceOneOf {
+  /**
+   * Source account details
+   */
+  export interface AccountTransactionSource extends TransactionsAPI.BaseTransactionSource {
+    /**
+     * Source account identifier
+     */
+    accountId: string;
+
+    sourceType: 'ACCOUNT';
+  }
+
+  /**
+   * UMA address source details
+   */
+  export interface UmaAddressTransactionSource extends TransactionsAPI.BaseTransactionSource {
+    sourceType: 'UMA_ADDRESS';
+
+    /**
+     * UMA address of the sender
+     */
+    umaAddress: string;
+  }
+}
+
+/**
+ * Status of a payment transaction
+ */
+export type TransactionStatus =
+  | 'CREATED'
+  | 'PENDING'
+  | 'PROCESSING'
+  | 'COMPLETED'
+  | 'REJECTED'
+  | 'FAILED'
+  | 'REFUNDED'
+  | 'EXPIRED';
+
+/**
+ * Type of transaction (incoming payment or outgoing payment)
+ */
+export type TransactionType = 'INCOMING' | 'OUTGOING';
+
+export interface TransactionListParams extends DefaultPaginationParams {
+  /**
+   * Filter by system customer ID
+   */
+  customerId?: string;
+
+  /**
+   * Filter by end date (inclusive) in ISO 8601 format
+   */
+  endDate?: string;
+
+  /**
+   * Maximum number of results to return (default 20, max 100)
+   */
+  limit?: number;
+
+  /**
+   * Filter by platform-specific customer ID
+   */
+  platformCustomerId?: string;
+
+  /**
+   * Filter by receiver account identifier
+   */
+  receiverAccountIdentifier?: string;
+
+  /**
+   * Filter by reference
+   */
+  reference?: string;
+
+  /**
+   * Filter by sender account identifier
+   */
+  senderAccountIdentifier?: string;
+
+  /**
+   * Order to sort results in
+   */
+  sortOrder?: 'asc' | 'desc';
+
+  /**
+   * Filter by start date (inclusive) in ISO 8601 format
+   */
+  startDate?: string;
+
+  /**
+   * Filter by transaction status
+   */
+  status?: TransactionStatus;
+
+  /**
+   * Filter by transaction type
+   */
+  type?: TransactionType;
+}
+
+export interface TransactionApproveParams {
+  /**
+   * Information about the recipient, provided by the platform if requested in the
+   * original webhook via `requestedReceiverCustomerInfoFields`.
+   */
+  receiverCustomerInfo?: { [key: string]: unknown };
+}
+
+export interface TransactionRejectParams {
+  /**
+   * Optional reason for rejecting the payment. This is just for debugging purposes
+   * or can be used for a platform's own purposes.
+   */
+  reason?: string;
+}
+
+export declare namespace Transactions {
+  export {
+    type BaseTransactionSource as BaseTransactionSource,
+    type IncomingTransaction as IncomingTransaction,
+    type TransactionSourceOneOf as TransactionSourceOneOf,
+    type TransactionStatus as TransactionStatus,
+    type TransactionType as TransactionType,
+    type TransactionListParams as TransactionListParams,
+    type TransactionApproveParams as TransactionApproveParams,
+    type TransactionRejectParams as TransactionRejectParams,
+  };
+}
+
+export { type TransactionsDefaultPagination };

package/src/resources/transfer-in.ts

@@ -0,0 +1,193 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as TransferInAPI from './transfer-in';
+import * as TransactionsAPI from './transactions';
+import { APIPromise } from '../core/api-promise';
+import { DefaultPagination } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+export class TransferIn extends APIResource {
+  /**
+   * Transfer funds from an external account to an internal account for a specific
+   * customer. This endpoint should only be used for external account sources with
+   * pull functionality (e.g. ACH Pull). Otherwise, use the paymentInstructions on
+   * the internal account to deposit funds.
+   *
+   * @example
+   * ```ts
+   * const transaction = await client.transferIn.create({
+   *   destination: {
+   *     accountId:
+   *       'InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123',
+   *   },
+   *   source: {
+   *     accountId:
+   *       'ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965',
+   *   },
+   *   amount: 12550,
+   * });
+   * ```
+   */
+  create(params: TransferInCreateParams, options?: RequestOptions): APIPromise<Transaction> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/transfer-in', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type TransactionsDefaultPagination = DefaultPagination<Transaction>;
+
+export interface BaseTransactionDestination {
+  /**
+   * Currency code for the destination
+   */
+  currency?: string;
+}
+
+export interface Transaction {
+  /**
+   * Unique identifier for the transaction
+   */
+  id: string;
+
+  /**
+   * System ID of the customer (sender for outgoing, recipient for incoming)
+   */
+  customerId: string;
+
+  /**
+   * Destination account details
+   */
+  destination: Transaction.AccountTransactionDestination | Transaction.UmaAddressTransactionDestination;
+
+  /**
+   * Platform-specific ID of the customer (sender for outgoing, recipient for
+   * incoming)
+   */
+  platformCustomerId: string;
+
+  /**
+   * Status of a payment transaction
+   */
+  status: TransactionsAPI.TransactionStatus;
+
+  /**
+   * Type of transaction (incoming payment or outgoing payment)
+   */
+  type: TransactionsAPI.TransactionType;
+
+  /**
+   * Additional information about the counterparty, if available and relevant to the
+   * transaction and platform. Only applicable for transactions to/from UMA
+   * addresses.
+   */
+  counterpartyInformation?: { [key: string]: unknown };
+
+  /**
+   * When the transaction was created
+   */
+  createdAt?: string;
+
+  /**
+   * Optional memo or description for the payment
+   */
+  description?: string;
+
+  /**
+   * When the payment was or will be settled
+   */
+  settledAt?: string;
+
+  /**
+   * When the transaction was last updated
+   */
+  updatedAt?: string;
+}
+
+export namespace Transaction {
+  /**
+   * Destination account details
+   */
+  export interface AccountTransactionDestination extends TransferInAPI.BaseTransactionDestination {
+    /**
+     * Destination account identifier
+     */
+    accountId: string;
+
+    destinationType: 'ACCOUNT';
+  }
+
+  /**
+   * UMA address destination details
+   */
+  export interface UmaAddressTransactionDestination extends TransferInAPI.BaseTransactionDestination {
+    destinationType: 'UMA_ADDRESS';
+
+    /**
+     * UMA address of the recipient
+     */
+    umaAddress: string;
+  }
+}
+
+export interface TransferInCreateParams {
+  /**
+   * Body param: Destination internal account details
+   */
+  destination: TransferInCreateParams.Destination;
+
+  /**
+   * Body param: Source external account details
+   */
+  source: TransferInCreateParams.Source;
+
+  /**
+   * Body param: Amount in the smallest unit of the currency (e.g., cents for
+   * USD/EUR, satoshis for BTC)
+   */
+  amount?: number;
+
+  /**
+   * Header param: A unique identifier for the request. If the same key is sent
+   * multiple times, the server will return the same response as the first request.
+   */
+  'Idempotency-Key'?: string;
+}
+
+export namespace TransferInCreateParams {
+  /**
+   * Destination internal account details
+   */
+  export interface Destination {
+    /**
+     * Reference to an internal account ID
+     */
+    accountId: string;
+  }
+
+  /**
+   * Source external account details
+   */
+  export interface Source {
+    /**
+     * Reference to an external account ID
+     */
+    accountId: string;
+  }
+}
+
+export declare namespace TransferIn {
+  export {
+    type BaseTransactionDestination as BaseTransactionDestination,
+    type Transaction as Transaction,
+    type TransferInCreateParams as TransferInCreateParams,
+  };
+}

package/src/resources/transfer-out.ts

@@ -0,0 +1,90 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as TransferInAPI from './transfer-in';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+export class TransferOut extends APIResource {
+  /**
+   * Transfer funds from an internal account to an external account for a specific
+   * customer.
+   *
+   * @example
+   * ```ts
+   * const transaction = await client.transferOut.create({
+   *   destination: {
+   *     accountId:
+   *       'ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965',
+   *   },
+   *   source: {
+   *     accountId:
+   *       'InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123',
+   *   },
+   *   amount: 12550,
+   * });
+   * ```
+   */
+  create(params: TransferOutCreateParams, options?: RequestOptions): APIPromise<TransferInAPI.Transaction> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/transfer-out', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface TransferOutCreateParams {
+  /**
+   * Body param: Destination external account details
+   */
+  destination: TransferOutCreateParams.Destination;
+
+  /**
+   * Body param: Source internal account details
+   */
+  source: TransferOutCreateParams.Source;
+
+  /**
+   * Body param: Amount in the smallest unit of the currency (e.g., cents for
+   * USD/EUR, satoshis for BTC)
+   */
+  amount?: number;
+
+  /**
+   * Header param: A unique identifier for the request. If the same key is sent
+   * multiple times, the server will return the same response as the first request.
+   */
+  'Idempotency-Key'?: string;
+}
+
+export namespace TransferOutCreateParams {
+  /**
+   * Destination external account details
+   */
+  export interface Destination {
+    /**
+     * Reference to an external account ID
+     */
+    accountId: string;
+  }
+
+  /**
+   * Source internal account details
+   */
+  export interface Source {
+    /**
+     * Reference to an internal account ID
+     */
+    accountId: string;
+  }
+}
+
+export declare namespace TransferOut {
+  export { type TransferOutCreateParams as TransferOutCreateParams };
+}

package/src/resources/uma-providers.ts

@@ -0,0 +1,98 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as QuotesAPI from './quotes';
+import { DefaultPagination, type DefaultPaginationParams, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+
+export class UmaProviders extends APIResource {
+  /**
+   * Retrieve a list of available Counterparty Providers. The response includes basic
+   * information about each provider, such as its UMA address, name, and supported
+   * currencies.
+   */
+  list(
+    query: UmaProviderListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<UmaProviderListResponsesDefaultPagination, UmaProviderListResponse> {
+    return this._client.getAPIList('/uma-providers', DefaultPagination<UmaProviderListResponse>, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export type UmaProviderListResponsesDefaultPagination = DefaultPagination<UmaProviderListResponse>;
+
+export interface UmaProviderListResponse {
+  /**
+   * Whether this UMA Provider is on your allow list
+   */
+  allowListStatus?: boolean;
+
+  /**
+   * Domain this VASP uses for UMA addresses
+   */
+  domain?: string;
+
+  /**
+   * Legal Entity Identifier for the UMA Provider
+   */
+  lei?: string;
+
+  /**
+   * Logo URL for the VASP
+   */
+  logoUrl?: string;
+
+  /**
+   * Name of the UMA Provider
+   */
+  name?: string;
+
+  /**
+   * List of currencies supported by this UMA Provider
+   */
+  supportedCurrencies?: Array<QuotesAPI.Currency>;
+
+  /**
+   * Region(s) this UMA Provider operates in
+   */
+  supportedRegions?: Array<string>;
+}
+
+export interface UmaProviderListParams extends DefaultPaginationParams {
+  /**
+   * The alpha-2 representation of a country, as defined by the ISO 3166-1 standard.
+   */
+  countryCode?: string;
+
+  /**
+   * The ISO 4217 currency code to filter providers by supported currency.
+   */
+  currencyCode?: string;
+
+  /**
+   * Whether to include providers which are not on your allowlist in the response. By
+   * default the response will include blocked providers.
+   */
+  hasBlockedProviders?: boolean;
+
+  /**
+   * Maximum number of results to return (default 20, max 100)
+   */
+  limit?: number;
+
+  /**
+   * Order to sort results in
+   */
+  sortOrder?: 'asc' | 'desc';
+}
+
+export declare namespace UmaProviders {
+  export {
+    type UmaProviderListResponse as UmaProviderListResponse,
+    type UmaProviderListResponsesDefaultPagination as UmaProviderListResponsesDefaultPagination,
+    type UmaProviderListParams as UmaProviderListParams,
+  };
+}