@lightsparkdev/grid 0.2.1

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { LightsparkGridError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new LightsparkGridError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new LightsparkGridError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new LightsparkGridError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new LightsparkGridError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new LightsparkGridError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/config.ts

@@ -0,0 +1,178 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as ReceiverAPI from './receiver';
+import * as TransactionsAPI from './transactions';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Config extends APIResource {
+  /**
+   * Retrieve the current platform configuration
+   *
+   * @example
+   * ```ts
+   * const platformConfig = await client.config.retrieve();
+   * ```
+   */
+  retrieve(options?: RequestOptions): APIPromise<PlatformConfig> {
+    return this._client.get('/config', options);
+  }
+
+  /**
+   * Update the platform configuration settings
+   *
+   * @example
+   * ```ts
+   * const platformConfig = await client.config.update({
+   *   supportedCurrencies: [
+   *     {
+   *       currencyCode: 'USD',
+   *       minAmount: 100,
+   *       maxAmount: 1000000,
+   *       enabledTransactionTypes: ['OUTGOING', 'INCOMING'],
+   *       requiredCounterpartyFields: [
+   *         { name: 'FULL_NAME', mandatory: true },
+   *         { name: 'NATIONALITY', mandatory: true },
+   *         { name: 'BIRTH_DATE', mandatory: true },
+   *       ],
+   *     },
+   *   ],
+   *   umaDomain: 'mycompany.com',
+   *   webhookEndpoint: 'https://api.mycompany.com/webhooks/uma',
+   * });
+   * ```
+   */
+  update(body: ConfigUpdateParams, options?: RequestOptions): APIPromise<PlatformConfig> {
+    return this._client.patch('/config', { body, ...options });
+  }
+}
+
+/**
+ * Name of a type of field containing info about a platform's customer or
+ * counterparty customer.
+ */
+export type CustomerInfoFieldName =
+  | 'FULL_NAME'
+  | 'BIRTH_DATE'
+  | 'NATIONALITY'
+  | 'PHONE_NUMBER'
+  | 'EMAIL'
+  | 'POSTAL_ADDRESS'
+  | 'TAX_ID'
+  | 'REGISTRATION_NUMBER'
+  | 'USER_TYPE'
+  | 'COUNTRY_OF_RESIDENCE'
+  | 'ACCOUNT_IDENTIFIER'
+  | 'FI_LEGAL_ENTITY_NAME'
+  | 'FI_ADDRESS'
+  | 'PURPOSE_OF_PAYMENT'
+  | 'ULTIMATE_INSTITUTION_COUNTRY'
+  | 'IDENTIFIER';
+
+export interface PlatformConfig {
+  /**
+   * System-generated unique identifier
+   */
+  id?: string;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt?: string;
+
+  /**
+   * Whether the platform is a regulated financial institution. This is used to
+   * determine if the platform's customers must be KYC/KYB'd by Lightspark via the
+   * KYC link flow. This can only be set by Lightspark during platform creation.
+   */
+  isRegulatedFinancialInstitution?: boolean;
+
+  /**
+   * The subdomain that incoming requests will be proxied to
+   */
+  proxyUmaSubdomain?: string;
+
+  /**
+   * List of currencies supported by the platform. This is what the platform's
+   * customers are able to hold, send, and receive.
+   */
+  supportedCurrencies?: Array<PlatformCurrencyConfig>;
+
+  /**
+   * UMA domain for this platform
+   */
+  umaDomain?: string;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt?: string;
+
+  /**
+   * URL where webhook notifications will be sent
+   */
+  webhookEndpoint?: string;
+}
+
+export interface PlatformCurrencyConfig {
+  /**
+   * Three-letter currency code (ISO 4217)
+   */
+  currencyCode: string;
+
+  /**
+   * List of transaction types that are enabled for this currency.
+   */
+  enabledTransactionTypes: Array<TransactionsAPI.TransactionType>;
+
+  /**
+   * Maximum amount that can be sent in the smallest unit of this currency
+   */
+  maxAmount: number;
+
+  /**
+   * Minimum amount that can be sent in the smallest unit of this currency
+   */
+  minAmount: number;
+
+  /**
+   * List of fields which the platform requires from the counterparty institutions
+   * about counterparty customers. Platforms can set mandatory to false if the
+   * platform does not require the field, but would like to have it available. Some
+   * fields may be required by the underlying UMA provider.
+   */
+  requiredCounterpartyFields: Array<ReceiverAPI.CounterpartyFieldDefinition>;
+
+  /**
+   * List of fields that are required by the underlying UMA provider for this
+   * currency. If the counterparty does not provide these fields, quote requests will
+   * fail.
+   */
+  providerRequiredCounterpartyCustomerFields?: Array<CustomerInfoFieldName>;
+
+  /**
+   * List of customer info field names that are required by the underlying UMA
+   * provider when creating a customer for this currency. These fields must be
+   * supplied when creating or updating a customer if this currency is intended to be
+   * used by that customer. If no fields are required, this field is omitted.
+   */
+  providerRequiredCustomerFields?: Array<CustomerInfoFieldName>;
+}
+
+export interface ConfigUpdateParams {
+  supportedCurrencies?: Array<PlatformCurrencyConfig>;
+
+  umaDomain?: string;
+
+  webhookEndpoint?: string;
+}
+
+export declare namespace Config {
+  export {
+    type CustomerInfoFieldName as CustomerInfoFieldName,
+    type PlatformConfig as PlatformConfig,
+    type PlatformCurrencyConfig as PlatformCurrencyConfig,
+    type ConfigUpdateParams as ConfigUpdateParams,
+  };
+}

package/src/resources/customers/bulk.ts

@@ -0,0 +1,201 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+import { path } from '../../internal/utils/path';
+
+export class Bulk extends APIResource {
+  /**
+   * Retrieve the current status and results of a bulk customer import job. This
+   * endpoint can be used to track the progress of both CSV uploads.
+   *
+   * The response includes:
+   *
+   * - Overall job status
+   * - Progress statistics
+   * - Detailed error information for failed entries
+   * - Completion timestamp when finished
+   *
+   * @example
+   * ```ts
+   * const response = await client.customers.bulk.getJobStatus(
+   *   'jobId',
+   * );
+   * ```
+   */
+  getJobStatus(jobID: string, options?: RequestOptions): APIPromise<BulkGetJobStatusResponse> {
+    return this._client.get(path`/customers/bulk/jobs/${jobID}`, options);
+  }
+
+  /**
+   * Upload a CSV file containing customer information for bulk creation. The CSV
+   * file should follow a specific format with required and optional columns based on
+   * customer type.
+   *
+   * ### CSV Format
+   *
+   * The CSV file should have the following columns:
+   *
+   * Required columns for all customers:
+   *
+   * - umaAddress: The customer's UMA address (e.g., $john.doe@uma.domain.com)
+   * - platformCustomerId: Your platform's unique identifier for the customer
+   * - customerType: Either "INDIVIDUAL" or "BUSINESS"
+   *
+   * Required columns for individual customers:
+   *
+   * - fullName: Individual's full name
+   * - birthDate: Date of birth in YYYY-MM-DD format
+   * - addressLine1: Street address line 1
+   * - city: City
+   * - state: State/Province/Region
+   * - postalCode: Postal/ZIP code
+   * - country: Country code (ISO 3166-1 alpha-2)
+   *
+   * Required columns for business customers:
+   *
+   * - businessLegalName: Legal name of the business
+   * - addressLine1: Street address line 1
+   * - city: City
+   * - state: State/Province/Region
+   * - postalCode: Postal/ZIP code
+   * - country: Country code (ISO 3166-1 alpha-2)
+   *
+   * Optional columns for all customers:
+   *
+   * - addressLine2: Street address line 2
+   * - platformAccountId: Your platform's identifier for the bank account
+   * - description: Optional description for the customer
+   *
+   * Optional columns for individual customers:
+   *
+   * - email: Customer's email address
+   *
+   * Optional columns for business customers:
+   *
+   * - businessRegistrationNumber: Business registration number
+   * - businessTaxId: Tax identification number
+   *
+   * ### Example CSV
+   *
+   * ```csv
+   * umaAddress,platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,platformAccountId,businessLegalName
+   * john.doe@uma.domain.com,customer123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US
+   * acme@uma.domain.com,biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US
+   * ```
+   *
+   * The upload process is asynchronous and will return a job ID that can be used to
+   * track progress. You can monitor the job status using the
+   * `/customers/bulk/jobs/{jobId}` endpoint.
+   *
+   * @example
+   * ```ts
+   * const response = await client.customers.bulk.uploadCsv({
+   *   file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
+   */
+  uploadCsv(body: BulkUploadCsvParams, options?: RequestOptions): APIPromise<BulkUploadCsvResponse> {
+    return this._client.post(
+      '/customers/bulk/csv',
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+}
+
+export interface BulkGetJobStatusResponse {
+  /**
+   * Unique identifier for the bulk import job
+   */
+  jobId: string;
+
+  progress: BulkGetJobStatusResponse.Progress;
+
+  /**
+   * Current status of the job
+   */
+  status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+
+  /**
+   * Timestamp when the job completed (only present for COMPLETED or FAILED status)
+   */
+  completedAt?: string;
+
+  /**
+   * Detailed error information for failed entries
+   */
+  errors?: Array<BulkGetJobStatusResponse.Error>;
+}
+
+export namespace BulkGetJobStatusResponse {
+  export interface Progress {
+    /**
+     * Number of customers that failed to create
+     */
+    failed: number;
+
+    /**
+     * Number of customers processed so far
+     */
+    processed: number;
+
+    /**
+     * Number of customers successfully created
+     */
+    successful: number;
+
+    /**
+     * Total number of customers to process
+     */
+    total: number;
+  }
+
+  export interface Error {
+    /**
+     * Platform customer ID or row number for the failed entry
+     */
+    correlationId: string;
+
+    /**
+     * Error code
+     */
+    code?: string;
+
+    /**
+     * Additional error details
+     */
+    details?: { [key: string]: unknown };
+
+    /**
+     * Error message
+     */
+    message?: string;
+  }
+}
+
+export interface BulkUploadCsvResponse {
+  /**
+   * Unique identifier for the bulk import job
+   */
+  jobId: string;
+
+  status: 'PENDING' | 'PROCESSING';
+}
+
+export interface BulkUploadCsvParams {
+  /**
+   * CSV file containing customer information
+   */
+  file: Uploadable;
+}
+
+export declare namespace Bulk {
+  export {
+    type BulkGetJobStatusResponse as BulkGetJobStatusResponse,
+    type BulkUploadCsvResponse as BulkUploadCsvResponse,
+    type BulkUploadCsvParams as BulkUploadCsvParams,
+  };
+}