@orcarail/node 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,521 @@
+/**
+ * Configuration options for the OrcaRail client
+ */
+interface OrcaRailConfig {
+    /**
+     * Base URL for the OrcaRail API
+     * @default "https://api.orcarail.com/api/v1"
+     */
+    baseUrl?: string;
+    /**
+     * API version
+     * @default "v1"
+     */
+    apiVersion?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Parameters for creating a Payment Intent
+ */
+interface PaymentIntentCreateParams {
+    /**
+     * Amount to charge (e.g., "100.00")
+     */
+    amount: string;
+    /**
+     * Currency code (e.g., "usd")
+     */
+    currency: string;
+    /**
+     * Payment method types (must include "crypto")
+     * @default ["crypto"]
+     */
+    payment_method_types?: string[];
+    /**
+     * Token ID (e.g., USDC, USDT)
+     */
+    tokenId: number;
+    /**
+     * Network ID (e.g., Ethereum, Polygon)
+     */
+    networkId: number;
+    /**
+     * Return URL after payment completion
+     */
+    return_url: string;
+    /**
+     * Cancel URL if payment is canceled
+     */
+    cancel_url?: string | null;
+    /**
+     * Payment description
+     */
+    description?: string;
+    /**
+     * Custom metadata object
+     */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * ISO 8601 expiration timestamp
+     */
+    expires_at?: string | null;
+}
+/**
+ * Parameters for updating a Payment Intent
+ */
+interface PaymentIntentUpdateParams {
+    /**
+     * Updated amount
+     */
+    amount?: string;
+    /**
+     * Updated currency
+     */
+    currency?: string;
+    /**
+     * Updated payment method types
+     */
+    payment_method_types?: string[];
+    /**
+     * Updated token ID
+     */
+    tokenId?: number;
+    /**
+     * Updated network ID
+     */
+    networkId?: number;
+    /**
+     * Updated return URL
+     */
+    return_url?: string;
+    /**
+     * Updated cancel URL
+     */
+    cancel_url?: string | null;
+    /**
+     * Updated description
+     */
+    description?: string;
+    /**
+     * Updated metadata
+     */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * Updated expiration timestamp
+     */
+    expires_at?: string | null;
+}
+/**
+ * Parameters for confirming a Payment Intent
+ */
+interface PaymentIntentConfirmParams {
+    /**
+     * Client secret for the payment intent (from create/retrieve response)
+     */
+    client_secret: string;
+    /**
+     * Return URL after payment completion
+     */
+    return_url: string;
+}
+/**
+ * Payment Link object
+ */
+interface PaymentLink {
+    /**
+     * Payment link ID
+     */
+    id: number;
+    /**
+     * Unique slug
+     */
+    unique_slug?: string;
+    /**
+     * Payment link URL
+     */
+    link: string;
+}
+/**
+ * Latest transaction details
+ */
+interface LatestTransaction {
+    /**
+     * Transaction ID
+     */
+    id: string;
+    /**
+     * Transaction status
+     */
+    status: string;
+    /**
+     * Transaction hash
+     */
+    hash?: string;
+    /**
+     * Transaction amount
+     */
+    amount?: string;
+    /**
+     * Transaction address
+     */
+    address?: string;
+}
+/**
+ * Payment Intent object
+ */
+interface PaymentIntent {
+    /**
+     * Payment Intent ID (e.g., "pi_1234567890")
+     */
+    id: string;
+    /**
+     * Object type (always "payment_intent")
+     */
+    object: string;
+    /**
+     * Amount to charge
+     */
+    amount: string;
+    /**
+     * Currency code
+     */
+    currency: string;
+    /**
+     * Current status
+     */
+    status: string;
+    /**
+     * Payment method types
+     */
+    payment_method_types: string[];
+    /**
+     * Client secret used to confirm the payment intent from the frontend
+     */
+    client_secret?: string;
+    /**
+     * Checkout URL (clean URL without secrets)
+     */
+    checkout_url?: string;
+    /**
+     * Return URL
+     */
+    return_url: string;
+    /**
+     * Cancel URL
+     */
+    cancel_url?: string | null;
+    /**
+     * Payment description
+     */
+    description?: string | null;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown> | null;
+    /**
+     * Payment link object
+     */
+    payment_link?: PaymentLink;
+    /**
+     * Expiration timestamp
+     */
+    expiresAt?: string;
+    /**
+     * Latest transaction details (for complete intents)
+     */
+    latestTransaction?: LatestTransaction;
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+}
+/**
+ * Webhook event types
+ */
+type WebhookEventType = 'payment_intent.complete' | 'payment_intent.processing' | 'payment_intent.canceled' | 'payment_intent.requires_payment_method' | 'payment_intent.requires_confirmation';
+/**
+ * Webhook event data object
+ */
+interface WebhookEventData {
+    /**
+     * Payment Intent object
+     */
+    object: PaymentIntent;
+}
+/**
+ * Webhook event structure
+ */
+interface WebhookEvent {
+    /**
+     * Event type
+     */
+    type: WebhookEventType;
+    /**
+     * Event data
+     */
+    data: WebhookEventData;
+    /**
+     * Unix timestamp when the event was created
+     */
+    created: number;
+}
+
+/**
+ * HTTP client for making requests to the OrcaRail API
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly apiSecret;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(apiKey: string, apiSecret: string, config?: OrcaRailConfig);
+    /**
+     * Create Basic Auth header from API key and secret
+     */
+    private getAuthHeader;
+    /**
+     * Build full URL from path
+     */
+    private buildUrl;
+    /**
+     * Make an HTTP request with timeout and error handling
+     */
+    private request;
+    /**
+     * GET request
+     */
+    get<T>(path: string, requireAuth?: boolean): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(path: string, body?: unknown, requireAuth?: boolean): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(path: string, body?: unknown, requireAuth?: boolean): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(path: string, body?: unknown, requireAuth?: boolean): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, requireAuth?: boolean): Promise<T>;
+}
+
+/**
+ * Checkout resource for slug-based checkout flows (public endpoints)
+ */
+declare class Checkout {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get checkout details by slug
+     *
+     * @param slug - Checkout slug from the payment link URL
+     * @returns Checkout details including payment intent
+     */
+    get(slug: string): Promise<PaymentIntent & Record<string, unknown>>;
+    /**
+     * Cancel payment intent by checkout slug
+     *
+     * @param slug - Checkout slug from the payment link URL
+     * @returns The canceled payment intent and optional cancel_url for redirect
+     */
+    cancel(slug: string): Promise<PaymentIntent & {
+        cancel_url?: string;
+    }>;
+}
+
+/**
+ * Payment Intents resource for managing payment intents
+ */
+declare class PaymentIntents {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Create a new Payment Intent
+     *
+     * @param params - Payment Intent creation parameters
+     * @returns The created Payment Intent
+     */
+    create(params: PaymentIntentCreateParams): Promise<PaymentIntent>;
+    /**
+     * Retrieve a Payment Intent by ID
+     *
+     * @param id - Payment Intent ID (e.g., "pi_1234567890")
+     * @returns The Payment Intent
+     */
+    retrieve(id: string): Promise<PaymentIntent>;
+    /**
+     * Cancel a Payment Intent (API: POST /payment_intents/:id/cancel).
+     * Use when the user is redirected to your cancel_url (e.g. https://yourapp.com/cancel?payment_intent=pi_20)
+     * and you want to mark the intent as canceled on the backend.
+     *
+     * @param id - Payment Intent ID (e.g. "pi_20" or "20")
+     * @returns The canceled Payment Intent
+     *
+     * @example
+     * // When user lands on https://localhost:3001/cancel?payment_intent=pi_20
+     * const intent = await orcarail.paymentIntents.cancel('pi_20');
+     */
+    cancel(id: string): Promise<PaymentIntent>;
+    /**
+     * Confirm a Payment Intent (API: POST /payment_intents/:id/confirm).
+     * Redirects the customer to the hosted checkout page.
+     *
+     * @param id - Payment Intent ID (e.g. "pi_20" or "20")
+     * @param params - Confirmation parameters including client_secret and return_url
+     * @returns The confirmed Payment Intent
+     *
+     * @example
+     * const intent = await orcarail.paymentIntents.confirm('pi_20', {
+     *   client_secret: intent.client_secret,
+     *   return_url: 'https://yourapp.com/return',
+     * });
+     */
+    confirm(id: string, params: PaymentIntentConfirmParams): Promise<PaymentIntent>;
+    /**
+     * Complete a Payment Intent (API: POST /payment_intents/:id/complete).
+     * Sets the intent to processing and fires the payment_intent.processing webhook.
+     * Use when the user is redirected to your success/return URL (e.g. https://yourapp.com/success?payment_intent=pi_34).
+     *
+     * @param id - Payment Intent ID (e.g. "pi_34" or "34")
+     * @returns The updated Payment Intent (status processing)
+     *
+     * @example
+     * // When user lands on https://localhost:3001/success?payment_intent=pi_34
+     * const intent = await orcarail.paymentIntents.complete('pi_34');
+     */
+    complete(id: string): Promise<PaymentIntent>;
+    /**
+     * Update a Payment Intent
+     *
+     * @param id - Payment Intent ID
+     * @param params - Update parameters (all optional)
+     * @returns The updated Payment Intent
+     */
+    update(id: string, params: PaymentIntentUpdateParams): Promise<PaymentIntent>;
+}
+
+/**
+ * Webhook utilities for verifying webhook signatures
+ */
+declare class Webhooks {
+    /**
+     * Verify webhook signature
+     *
+     * @param rawBody - Raw request body (string or Buffer)
+     * @param signature - Signature from x-webhook-signature header
+     * @param secret - Webhook secret (API key's secretHash)
+     * @returns True if signature is valid, false otherwise
+     */
+    verifySignature(rawBody: string | Buffer, signature: string, secret: string): boolean;
+    /**
+     * Construct and verify a webhook event from raw body and signature
+     *
+     * @param rawBody - Raw request body (string or Buffer)
+     * @param signature - Signature from x-webhook-signature header
+     * @param secret - Webhook secret (API key's secretHash)
+     * @returns Parsed webhook event
+     * @throws OrcaRailSignatureVerificationError if signature is invalid
+     */
+    constructEvent(rawBody: string | Buffer, signature: string, secret: string): WebhookEvent;
+}
+
+/**
+ * Base error class for all OrcaRail errors
+ */
+declare class OrcaRailError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the API returns a non-2xx status code
+ */
+declare class OrcaRailAPIError extends OrcaRailError {
+    /**
+     * HTTP status code
+     */
+    readonly statusCode: number;
+    /**
+     * Error type from the API response
+     */
+    readonly type?: string;
+    /**
+     * Additional error details from the API
+     */
+    readonly details?: unknown;
+    constructor(message: string, statusCode: number, type?: string, details?: unknown);
+}
+/**
+ * Error thrown when authentication fails (401)
+ */
+declare class OrcaRailAuthenticationError extends OrcaRailAPIError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when webhook signature verification fails
+ */
+declare class OrcaRailSignatureVerificationError extends OrcaRailError {
+    /**
+     * The signature that was provided
+     */
+    readonly signature: string;
+    constructor(message?: string, signature?: string);
+}
+
+/**
+ * OrcaRail Node.js SDK
+ *
+ * @example
+ * ```typescript
+ * import OrcaRail from '@orcarail/node';
+ *
+ * const orcarail = new OrcaRail('ak_live_xxx', 'sk_live_xxx');
+ *
+ * // Create a payment intent
+ * const intent = await orcarail.paymentIntents.create({
+ *   amount: '100.00',
+ *   currency: 'usd',
+ *   payment_method_types: ['crypto'],
+ *   tokenId: 1,
+ *   networkId: 1,
+ *   return_url: 'https://merchant.example.com/return',
+ * });
+ * ```
+ */
+declare class OrcaRail {
+    /**
+     * Payment Intents resource
+     */
+    readonly paymentIntents: PaymentIntents;
+    /**
+     * Checkout resource (slug-based get/cancel)
+     */
+    readonly checkout: Checkout;
+    /**
+     * Webhooks utilities
+     */
+    readonly webhooks: Webhooks;
+    private readonly client;
+    /**
+     * Create a new OrcaRail client instance
+     *
+     * @param apiKey - Your OrcaRail API key (e.g., "ak_live_xxx")
+     * @param apiSecret - Your OrcaRail API secret (e.g., "sk_live_xxx")
+     * @param config - Optional configuration
+     */
+    constructor(apiKey: string, apiSecret: string, config?: OrcaRailConfig);
+}
+
+// @ts-ignore
+export = OrcaRail;
+export { type LatestTransaction, OrcaRail, OrcaRailAPIError, OrcaRailAuthenticationError, type OrcaRailConfig, OrcaRailError, OrcaRailSignatureVerificationError, type PaymentIntent, type PaymentIntentConfirmParams, type PaymentIntentCreateParams, type PaymentIntentUpdateParams, type PaymentLink, type WebhookEvent, type WebhookEventData, type WebhookEventType };