@hypawave/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,315 @@
+interface HypawaveConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface CreateInvoiceParams {
+    client_email: string;
+    client_first_name: string;
+    client_last_name: string;
+    amount: number;
+    due_date: string;
+    company_name?: string;
+    description?: string;
+    currency?: string;
+    expires_in?: "1h" | "24h" | "7d" | null;
+    expires_at?: string | null;
+    creator_first_name?: string;
+    creator_last_name?: string;
+    creator_company_name?: string;
+    creator_fingerprint?: string;
+    /**
+     * Optional override for the Lightning payment destination (Lightning Address
+     * or LNURL-pay URL). Defaults to the API key owner's stored `lightning_address`.
+     * Override supports marketplace routing (per-invoice seller), multi-wallet
+     * owners, and pass-through flows where the agent facilitates for a third
+     * party. Funds always flow wallet-to-wallet — Hypawave remains non-custodial.
+     */
+    payment_destination?: string;
+    execution_webhook?: string;
+}
+interface CreateInvoiceResponse {
+    ok: true;
+    invoice_id: number;
+    access_token: string;
+    payment_url: string;
+    stream_id: string;
+    amount: number;
+    currency: string;
+    sats: number;
+    btc_usd_rate: number;
+    expires_at: string | null;
+}
+interface BalanceResponse {
+    available_sats: number;
+    fiat_equivalent: number;
+    currency: string;
+    btc_price: number;
+    has_outstanding_fee: boolean;
+}
+/**
+ * Top-ups are fee-settlement only. The server always mints a bolt11 for
+ * exactly the amount owed — callers cannot specify an amount. This interface
+ * is kept as an empty object for call-site stability.
+ */
+type TopupParams = Record<string, never>;
+interface TopupResponse {
+    ok: true;
+    bolt11: string;
+    payment_hash: string;
+    /** Exact owed amount the server quoted. */
+    amount_sats: number;
+    expires_at: string | null;
+    /** True if an existing pending top-up was returned instead of a fresh one. */
+    reused?: boolean;
+}
+interface UnlockStatusResponse {
+    unlocked: Record<string, boolean>;
+    statuses: Record<string, {
+        unlocked: boolean;
+        status: string;
+        failure_reason: string | null;
+        settlement_proof: {
+            payment_hash: string | null;
+            preimage: string | null;
+            settled_at: string | null;
+        } | null;
+    }>;
+}
+interface GetKeyResponse {
+    encryption_key: string;
+    iv_hex: string;
+    downloads_used: number;
+    max_downloads: number;
+    reclaim_window_hours: number;
+}
+interface ApiKeyInfo {
+    id: string;
+    key_prefix: string;
+    mode: "test" | "live";
+    label: string | null;
+    created_at: string;
+    revoked_at: string | null;
+    last_used_at: string | null;
+}
+interface UploadUrlParams {
+    fileName: string;
+    contentType: string;
+    fileSize?: number;
+}
+interface UploadUrlResponse {
+    signedUrl: string;
+    objectKey: string;
+}
+interface StoreFileParams {
+    invoice_id: number;
+    file_name: string;
+    encrypted_file_url: string;
+    iv_hex: string;
+    key_hash?: string;
+    size?: number;
+}
+interface StoreFileResponse {
+    ok: true;
+    id: string;
+}
+interface StoreFileKeyParams {
+    invoice_file_id: string;
+    key_b64: string;
+}
+interface ListInvoicesParams {
+    limit?: number;
+    offset?: number;
+    status?: "paid" | "not_paid" | "expired";
+}
+interface InvoiceItem {
+    invoice_id: number;
+    stream_id: string | null;
+    amount: number;
+    currency: string;
+    description: string | null;
+    status: "paid" | "pending" | "expired";
+    payment_destination: string | null;
+    access_token: string | null;
+    payment_url: string | null;
+    client_email: string | null;
+    client_first_name: string | null;
+    client_last_name: string | null;
+    created_at: string;
+    due_date: string;
+    expires_at: string | null;
+    has_file: boolean;
+    payment_hash: string | null;
+    preimage: string | null;
+    paid_at: string | null;
+}
+interface InvoiceFilesResponse {
+    files: Record<number, {
+        id: string;
+        encrypted_file_url: string;
+        file_name: string;
+    }[]>;
+}
+interface DownloadUrlResponse {
+    downloadUrl: string;
+}
+interface ListInvoicesResponse {
+    invoices: InvoiceItem[];
+    has_more: boolean;
+}
+interface GetBolt11Response {
+    pr: string;
+    routes: unknown[];
+    terms_hash: string;
+}
+interface ConfirmPaymentParams {
+    payment_hash: string;
+    preimage: string;
+    terms_hash?: string;
+}
+interface ConfirmPaymentResponse {
+    ok: true;
+    already_settled: boolean;
+}
+interface ReceiptResponse {
+    receipt: {
+        invoice_id: number;
+        status: "settled";
+        amount: number;
+        currency: string;
+        amount_sats: number | null;
+        description: string | null;
+        creator: {
+            first_name: string | null;
+            last_name: string | null;
+            company: string | null;
+        };
+        created_at: string;
+        settled_at: string | null;
+        expires_at: string | null;
+        payment_hash: string | null;
+        preimage: string | null;
+        receipt_verified: boolean;
+        has_files: boolean;
+        file_count: number;
+    };
+}
+interface PublicSettingsResponse {
+    min_topup_sats: number;
+    min_topup_usd: number | null;
+    fee_percent: number;
+    min_invoice_usd: number;
+    max_invoice_usd: number;
+    max_file_size_mb: number;
+    max_files_per_invoice: number;
+    btc_usd_price: number | null;
+}
+interface PaymentPayload {
+    protocol: "hypawave/v1";
+    invoice_id: number;
+    amount: number;
+    currency: string;
+    sats: number;
+    btc_usd_rate: number;
+    description: string | null;
+    expires_at: string | null;
+    bolt11_url: string;
+    confirm_url: string;
+    payment_url: string;
+    spec_url: string;
+    instructions_url: string;
+}
+interface OfferDownloadUrlParams {
+    offer_file_id: string;
+    claim_token?: string;
+    preimage?: string;
+}
+interface WalletCapabilities {
+    returnsPreimage: true | false | "conditional";
+}
+interface WalletAdapter {
+    capabilities: WalletCapabilities;
+    payInvoice(bolt11: string): Promise<{
+        payment_hash: string;
+        preimage: string;
+        fees_paid_msat?: number;
+        raw?: unknown;
+    }>;
+}
+interface PayAndConfirmParams {
+    invoiceId: number;
+    accessToken: string;
+    wallet: WalletAdapter;
+    allowConditionalPreimage?: boolean;
+}
+interface PayAndConfirmResult {
+    payment_hash: string;
+    preimage: string;
+    terms_hash: string;
+    fees_paid_msat?: number;
+    confirmation: ConfirmPaymentResponse;
+}
+interface HypawaveError {
+    error: string;
+    message?: string;
+    field?: string;
+}
+
+declare class Hypawave {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: HypawaveConfig);
+    private request;
+    createInvoice(params: CreateInvoiceParams): Promise<CreateInvoiceResponse>;
+    getBolt11(accessToken: string): Promise<GetBolt11Response>;
+    confirmPayment(invoiceId: number, params: ConfirmPaymentParams): Promise<ConfirmPaymentResponse>;
+    getPaymentPayload(params: CreateInvoiceParams, response: CreateInvoiceResponse): PaymentPayload;
+    getBalance(currency?: string): Promise<BalanceResponse>;
+    /**
+     * Request a fee-settlement top-up invoice. The server mints a bolt11 for
+     * exactly the amount owed — balance can never exceed 0. No arguments are
+     * needed; any amount fields in a passed params object are ignored.
+     *
+     * Throws API errors:
+     *   - topup_not_needed   — balance is already ≥ 0
+     *   - duplicate_topup    — a pending top-up invoice already exists
+     */
+    topup(_params?: TopupParams): Promise<TopupResponse>;
+    getUnlockStatus(invoiceIds: number[]): Promise<UnlockStatusResponse>;
+    getKey(invoiceFileId: string, token?: string): Promise<GetKeyResponse>;
+    getUploadUrl(params: UploadUrlParams): Promise<UploadUrlResponse>;
+    storeFile(params: StoreFileParams): Promise<StoreFileResponse>;
+    storeFileKey(params: StoreFileKeyParams): Promise<{
+        ok: true;
+    }>;
+    listInvoices(params?: ListInvoicesParams): Promise<ListInvoicesResponse>;
+    getInvoiceFiles(invoiceIds: number[], token?: string): Promise<InvoiceFilesResponse>;
+    getDownloadUrl(invoiceFileId: string, token?: string): Promise<DownloadUrlResponse>;
+    getOfferDownloadUrl(paymentIntentId: string, params: OfferDownloadUrlParams): Promise<DownloadUrlResponse>;
+    getReceipt(invoiceId: number): Promise<ReceiptResponse>;
+    getPayerReceipt(invoiceId: number, preimage: string): Promise<ReceiptResponse>;
+    getSettings(): Promise<PublicSettingsResponse>;
+    waitForSettlement(invoiceId: number, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<UnlockStatusResponse["statuses"][string]>;
+    payAndConfirm(params: PayAndConfirmParams): Promise<PayAndConfirmResult>;
+}
+
+declare class HypawaveAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly field?: string;
+    constructor(status: number, body: {
+        error: string;
+        message?: string;
+        field?: string;
+    });
+    get isAuth(): boolean;
+    get isRateLimit(): boolean;
+    get isValidation(): boolean;
+    get isOutstandingFee(): boolean;
+}
+
+export { type ApiKeyInfo, type BalanceResponse, type ConfirmPaymentParams, type ConfirmPaymentResponse, type CreateInvoiceParams, type CreateInvoiceResponse, type DownloadUrlResponse, type GetBolt11Response, type GetKeyResponse, Hypawave, HypawaveAPIError, type HypawaveConfig, type HypawaveError, type InvoiceFilesResponse, type InvoiceItem, type ListInvoicesParams, type ListInvoicesResponse, type OfferDownloadUrlParams, type PayAndConfirmParams, type PayAndConfirmResult, type PaymentPayload, type PublicSettingsResponse, type ReceiptResponse, type StoreFileKeyParams, type StoreFileParams, type StoreFileResponse, type TopupParams, type TopupResponse, type UnlockStatusResponse, type UploadUrlParams, type UploadUrlResponse, type WalletAdapter, type WalletCapabilities };

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+interface HypawaveConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface CreateInvoiceParams {
+    client_email: string;
+    client_first_name: string;
+    client_last_name: string;
+    amount: number;
+    due_date: string;
+    company_name?: string;
+    description?: string;
+    currency?: string;
+    expires_in?: "1h" | "24h" | "7d" | null;
+    expires_at?: string | null;
+    creator_first_name?: string;
+    creator_last_name?: string;
+    creator_company_name?: string;
+    creator_fingerprint?: string;
+    /**
+     * Optional override for the Lightning payment destination (Lightning Address
+     * or LNURL-pay URL). Defaults to the API key owner's stored `lightning_address`.
+     * Override supports marketplace routing (per-invoice seller), multi-wallet
+     * owners, and pass-through flows where the agent facilitates for a third
+     * party. Funds always flow wallet-to-wallet — Hypawave remains non-custodial.
+     */
+    payment_destination?: string;
+    execution_webhook?: string;
+}
+interface CreateInvoiceResponse {
+    ok: true;
+    invoice_id: number;
+    access_token: string;
+    payment_url: string;
+    stream_id: string;
+    amount: number;
+    currency: string;
+    sats: number;
+    btc_usd_rate: number;
+    expires_at: string | null;
+}
+interface BalanceResponse {
+    available_sats: number;
+    fiat_equivalent: number;
+    currency: string;
+    btc_price: number;
+    has_outstanding_fee: boolean;
+}
+/**
+ * Top-ups are fee-settlement only. The server always mints a bolt11 for
+ * exactly the amount owed — callers cannot specify an amount. This interface
+ * is kept as an empty object for call-site stability.
+ */
+type TopupParams = Record<string, never>;
+interface TopupResponse {
+    ok: true;
+    bolt11: string;
+    payment_hash: string;
+    /** Exact owed amount the server quoted. */
+    amount_sats: number;
+    expires_at: string | null;
+    /** True if an existing pending top-up was returned instead of a fresh one. */
+    reused?: boolean;
+}
+interface UnlockStatusResponse {
+    unlocked: Record<string, boolean>;
+    statuses: Record<string, {
+        unlocked: boolean;
+        status: string;
+        failure_reason: string | null;
+        settlement_proof: {
+            payment_hash: string | null;
+            preimage: string | null;
+            settled_at: string | null;
+        } | null;
+    }>;
+}
+interface GetKeyResponse {
+    encryption_key: string;
+    iv_hex: string;
+    downloads_used: number;
+    max_downloads: number;
+    reclaim_window_hours: number;
+}
+interface ApiKeyInfo {
+    id: string;
+    key_prefix: string;
+    mode: "test" | "live";
+    label: string | null;
+    created_at: string;
+    revoked_at: string | null;
+    last_used_at: string | null;
+}
+interface UploadUrlParams {
+    fileName: string;
+    contentType: string;
+    fileSize?: number;
+}
+interface UploadUrlResponse {
+    signedUrl: string;
+    objectKey: string;
+}
+interface StoreFileParams {
+    invoice_id: number;
+    file_name: string;
+    encrypted_file_url: string;
+    iv_hex: string;
+    key_hash?: string;
+    size?: number;
+}
+interface StoreFileResponse {
+    ok: true;
+    id: string;
+}
+interface StoreFileKeyParams {
+    invoice_file_id: string;
+    key_b64: string;
+}
+interface ListInvoicesParams {
+    limit?: number;
+    offset?: number;
+    status?: "paid" | "not_paid" | "expired";
+}
+interface InvoiceItem {
+    invoice_id: number;
+    stream_id: string | null;
+    amount: number;
+    currency: string;
+    description: string | null;
+    status: "paid" | "pending" | "expired";
+    payment_destination: string | null;
+    access_token: string | null;
+    payment_url: string | null;
+    client_email: string | null;
+    client_first_name: string | null;
+    client_last_name: string | null;
+    created_at: string;
+    due_date: string;
+    expires_at: string | null;
+    has_file: boolean;
+    payment_hash: string | null;
+    preimage: string | null;
+    paid_at: string | null;
+}
+interface InvoiceFilesResponse {
+    files: Record<number, {
+        id: string;
+        encrypted_file_url: string;
+        file_name: string;
+    }[]>;
+}
+interface DownloadUrlResponse {
+    downloadUrl: string;
+}
+interface ListInvoicesResponse {
+    invoices: InvoiceItem[];
+    has_more: boolean;
+}
+interface GetBolt11Response {
+    pr: string;
+    routes: unknown[];
+    terms_hash: string;
+}
+interface ConfirmPaymentParams {
+    payment_hash: string;
+    preimage: string;
+    terms_hash?: string;
+}
+interface ConfirmPaymentResponse {
+    ok: true;
+    already_settled: boolean;
+}
+interface ReceiptResponse {
+    receipt: {
+        invoice_id: number;
+        status: "settled";
+        amount: number;
+        currency: string;
+        amount_sats: number | null;
+        description: string | null;
+        creator: {
+            first_name: string | null;
+            last_name: string | null;
+            company: string | null;
+        };
+        created_at: string;
+        settled_at: string | null;
+        expires_at: string | null;
+        payment_hash: string | null;
+        preimage: string | null;
+        receipt_verified: boolean;
+        has_files: boolean;
+        file_count: number;
+    };
+}
+interface PublicSettingsResponse {
+    min_topup_sats: number;
+    min_topup_usd: number | null;
+    fee_percent: number;
+    min_invoice_usd: number;
+    max_invoice_usd: number;
+    max_file_size_mb: number;
+    max_files_per_invoice: number;
+    btc_usd_price: number | null;
+}
+interface PaymentPayload {
+    protocol: "hypawave/v1";
+    invoice_id: number;
+    amount: number;
+    currency: string;
+    sats: number;
+    btc_usd_rate: number;
+    description: string | null;
+    expires_at: string | null;
+    bolt11_url: string;
+    confirm_url: string;
+    payment_url: string;
+    spec_url: string;
+    instructions_url: string;
+}
+interface OfferDownloadUrlParams {
+    offer_file_id: string;
+    claim_token?: string;
+    preimage?: string;
+}
+interface WalletCapabilities {
+    returnsPreimage: true | false | "conditional";
+}
+interface WalletAdapter {
+    capabilities: WalletCapabilities;
+    payInvoice(bolt11: string): Promise<{
+        payment_hash: string;
+        preimage: string;
+        fees_paid_msat?: number;
+        raw?: unknown;
+    }>;
+}
+interface PayAndConfirmParams {
+    invoiceId: number;
+    accessToken: string;
+    wallet: WalletAdapter;
+    allowConditionalPreimage?: boolean;
+}
+interface PayAndConfirmResult {
+    payment_hash: string;
+    preimage: string;
+    terms_hash: string;
+    fees_paid_msat?: number;
+    confirmation: ConfirmPaymentResponse;
+}
+interface HypawaveError {
+    error: string;
+    message?: string;
+    field?: string;
+}
+
+declare class Hypawave {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: HypawaveConfig);
+    private request;
+    createInvoice(params: CreateInvoiceParams): Promise<CreateInvoiceResponse>;
+    getBolt11(accessToken: string): Promise<GetBolt11Response>;
+    confirmPayment(invoiceId: number, params: ConfirmPaymentParams): Promise<ConfirmPaymentResponse>;
+    getPaymentPayload(params: CreateInvoiceParams, response: CreateInvoiceResponse): PaymentPayload;
+    getBalance(currency?: string): Promise<BalanceResponse>;
+    /**
+     * Request a fee-settlement top-up invoice. The server mints a bolt11 for
+     * exactly the amount owed — balance can never exceed 0. No arguments are
+     * needed; any amount fields in a passed params object are ignored.
+     *
+     * Throws API errors:
+     *   - topup_not_needed   — balance is already ≥ 0
+     *   - duplicate_topup    — a pending top-up invoice already exists
+     */
+    topup(_params?: TopupParams): Promise<TopupResponse>;
+    getUnlockStatus(invoiceIds: number[]): Promise<UnlockStatusResponse>;
+    getKey(invoiceFileId: string, token?: string): Promise<GetKeyResponse>;
+    getUploadUrl(params: UploadUrlParams): Promise<UploadUrlResponse>;
+    storeFile(params: StoreFileParams): Promise<StoreFileResponse>;
+    storeFileKey(params: StoreFileKeyParams): Promise<{
+        ok: true;
+    }>;
+    listInvoices(params?: ListInvoicesParams): Promise<ListInvoicesResponse>;
+    getInvoiceFiles(invoiceIds: number[], token?: string): Promise<InvoiceFilesResponse>;
+    getDownloadUrl(invoiceFileId: string, token?: string): Promise<DownloadUrlResponse>;
+    getOfferDownloadUrl(paymentIntentId: string, params: OfferDownloadUrlParams): Promise<DownloadUrlResponse>;
+    getReceipt(invoiceId: number): Promise<ReceiptResponse>;
+    getPayerReceipt(invoiceId: number, preimage: string): Promise<ReceiptResponse>;
+    getSettings(): Promise<PublicSettingsResponse>;
+    waitForSettlement(invoiceId: number, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<UnlockStatusResponse["statuses"][string]>;
+    payAndConfirm(params: PayAndConfirmParams): Promise<PayAndConfirmResult>;
+}
+
+declare class HypawaveAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly field?: string;
+    constructor(status: number, body: {
+        error: string;
+        message?: string;
+        field?: string;
+    });
+    get isAuth(): boolean;
+    get isRateLimit(): boolean;
+    get isValidation(): boolean;
+    get isOutstandingFee(): boolean;
+}
+
+export { type ApiKeyInfo, type BalanceResponse, type ConfirmPaymentParams, type ConfirmPaymentResponse, type CreateInvoiceParams, type CreateInvoiceResponse, type DownloadUrlResponse, type GetBolt11Response, type GetKeyResponse, Hypawave, HypawaveAPIError, type HypawaveConfig, type HypawaveError, type InvoiceFilesResponse, type InvoiceItem, type ListInvoicesParams, type ListInvoicesResponse, type OfferDownloadUrlParams, type PayAndConfirmParams, type PayAndConfirmResult, type PaymentPayload, type PublicSettingsResponse, type ReceiptResponse, type StoreFileKeyParams, type StoreFileParams, type StoreFileResponse, type TopupParams, type TopupResponse, type UnlockStatusResponse, type UploadUrlParams, type UploadUrlResponse, type WalletAdapter, type WalletCapabilities };