gwop-checkout 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# gwop-checkout
+
+Stripe-like Gwop payment primitives for **self-hosted** stores.
+
+Use this SDK when your catalog, fulfillment, and user model live in your own service, and you only want Gwop for checkout and settlement.
+
+## Product boundary
+
+Included:
+- Merchant provisioning (`/v1/merchants/*`)
+- Invoice lifecycle (`/v1/invoices*`)
+- Webhook signature verification helper
+
+Not included:
+- Hosted storefront (`/store/*`, `/v1/merchants/store/*`)
+- Hosted delivery recovery (`/v1/invoices/{id}/delivery`)
+
+## Install
+
+```bash
+npm install gwop-checkout
+```
+
+## Configuration
+
+```bash
+# Store backend env
+GWOP_CHECKOUT_API_KEY=sk_m_xxx
+GWOP_API_BASE=https://api.gwop.io
+GWOP_WEBHOOK_SECRET=whsec_xxx
+```
+
+## Quick start
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { GwopCheckout } from 'gwop-checkout';
+
+const gwop = new GwopCheckout({
+  merchantApiKey: process.env.GWOP_CHECKOUT_API_KEY,
+  baseUrl: process.env.GWOP_API_BASE || 'https://api.gwop.io',
+});
+
+const created = await gwop.invoices.create(
+  {
+    amount_usdc: 10_000,
+    description: 'Speak credits: tts-5k',
+    metadata: { order_id: 'ord_123', sku: 'tts-5k' },
+    consumption_type: 'consumable',
+  },
+  { idempotencyKey: randomUUID() },
+);
+
+// Retrieve public payment fields for your client.
+const invoice = await gwop.invoices.retrieve(created.id);
+console.log(invoice.gwop_pay_url, invoice.payment_address);
+```
+
+## Store integration pattern (recommended)
+
+1. Store receives `POST /buy` with `{ sku, quantity }`.
+2. Store calculates amount and creates a Gwop invoice with `gwop.invoices.create(...)`.
+3. Store retrieves invoice public fields with `gwop.invoices.retrieve(id)`.
+4. Store returns `pay_url` + `invoice_id` + local `order_id` to the client/agent.
+5. Gwop sends webhook (`invoice.paid|invoice.expired|invoice.canceled`) to store.
+6. Store verifies signature with `Webhooks.constructEvent(...)` and updates local order state.
+7. Store fulfills product in its own infrastructure.
+
+This keeps checkout state in Gwop and business/fulfillment state in your store.
+
+## Webhook verification
+
+```ts
+import { Webhooks } from 'gwop-checkout';
+
+const webhooks = new Webhooks();
+const event = webhooks.constructEvent(
+  rawBody, // exact raw request body string
+  req.headers['x-gwop-signature'] as string | undefined,
+  process.env.GWOP_WEBHOOK_SECRET!,
+);
+
+if (event.event_type === 'invoice.paid') {
+  // mark order paid, allow fulfillment/claim
+}
+```
+
+## SDK methods
+
+Merchants:
+- `merchants.getInitPreflight()`
+- `merchants.init(body, { idempotencyKey })`
+- `merchants.getStatus()`
+- `merchants.updateSettings(body)`
+- `merchants.generateWebhookSecret()`
+
+Invoices:
+- `invoices.create(body, { idempotencyKey? })`
+- `invoices.list(params?)`
+- `invoices.retrieve(invoiceId)`
+- `invoices.cancel(invoiceId)`
+- `invoices.pay(invoiceId, body?)` (requires agent key)
+- `invoices.verifyExternalPayment(invoiceId, { tx_signature })`
+
+Client key setters:
+- `setMerchantApiKey(sk_m_...)`
+- `setAgentApiKey(sk_...)`
+
+## Notes
+
+- Recommended env var name: `GWOP_CHECKOUT_API_KEY`.
+- Merchant-auth endpoints require `sk_m_*` keys.
+- `invoices.pay` requires an `sk_*` agent key.
+- `invoices.retrieve` and `invoices.verifyExternalPayment` are public endpoints.
+
+## Package docs
+
+- Contract (YAML): `packages/gwop-checkout/docs/gwop-checkout-profile.yaml`
+- Contract summary (MD): `packages/gwop-checkout/docs/gwop-checkout-profile.md`

package/dist/index.d.mts

@@ -0,0 +1,346 @@
+type Currency = 'USDC';
+type InvoiceStatus = 'OPEN' | 'PAYING' | 'PAID' | 'EXPIRED' | 'CANCELED';
+type ConsumptionType = 'redeliverable' | 'consumable';
+interface GwopCheckoutConfig {
+    baseUrl?: string;
+    merchantApiKey?: string;
+    agentApiKey?: string;
+}
+interface PublicRequestOptions {
+    signal?: AbortSignal;
+}
+interface AuthenticatedRequestOptions extends PublicRequestOptions {
+    apiKey?: string;
+}
+interface IdempotentRequestOptions extends AuthenticatedRequestOptions {
+    idempotencyKey?: string;
+}
+interface RequiredIdempotencyRequestOptions extends PublicRequestOptions {
+    idempotencyKey: string;
+}
+interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        requestId?: string;
+    };
+}
+interface FieldRequirement {
+    type: 'string' | 'email' | 'url';
+    required: boolean;
+    critical?: boolean;
+    min_length?: number;
+    max_length?: number;
+    pattern?: string;
+    guidance: string;
+}
+interface MerchantInitPreflight {
+    required_fields: {
+        email: FieldRequirement;
+        merchant_name: FieldRequirement;
+        merchant_description: FieldRequirement;
+    };
+    optional_fields: {
+        webhook_url: FieldRequirement;
+    };
+    warnings: string[];
+    checklist: string[];
+    example_request: {
+        method: string;
+        path: string;
+        headers: Record<string, unknown>;
+        body: Record<string, unknown>;
+    };
+}
+interface MerchantInitRequest {
+    email: string;
+    merchant_name: string;
+    merchant_description: string;
+    webhook_url?: string;
+}
+interface MerchantCapabilities {
+    create_invoices: boolean;
+    receive_payments: boolean;
+    create_products: boolean;
+    withdraw: boolean;
+}
+interface MerchantInitResponse {
+    status: 'ACTIVE';
+    wallet_address: string;
+    api_key: string;
+    claim_url: string;
+    claim_expires_at: string | null;
+    claim_email_sent: boolean;
+    help_endpoint: string;
+    capabilities: MerchantCapabilities;
+    agent_guidance: {
+        message?: string;
+        persist?: string[];
+        next_step?: string;
+    };
+}
+interface MerchantStatusResponse {
+    status: 'ACTIVE' | 'SUSPENDED';
+    claimed: boolean;
+    wallet_address: string;
+    merchant_name: string;
+    capabilities: MerchantCapabilities;
+    balance_usdc?: number;
+    pending_balance_usdc?: number;
+    claim_url?: string;
+    owner_email_verified?: boolean;
+    withdrawal_address?: string;
+}
+interface MerchantSettingsUpdateRequestPublic {
+    webhook_url?: string;
+    business_name?: string;
+    withdrawal_address?: string;
+}
+interface MerchantProfilePublic {
+    id: string;
+    email?: string | null;
+    business_name: string;
+    website?: string | null;
+    solana_address?: string | null;
+    withdrawal_address?: string | null;
+    webhook_url?: string | null;
+    webhook_secret_preview?: string | null;
+    status: 'PENDING_SETUP' | 'ACTIVE' | 'SUSPENDED';
+    verified_at?: string | null;
+    created_at: string;
+}
+interface WebhookSecretResponse {
+    secret: string;
+    preview: string;
+    note: string;
+}
+interface CreateInvoiceRequest {
+    amount_usdc: number;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    metadata_public?: boolean;
+    expires_in_seconds?: number;
+    consumption_type?: ConsumptionType;
+    replay_window_seconds?: number;
+    max_replays?: number;
+}
+interface CreateInvoiceResponse {
+    id: string;
+    merchant_id: string;
+    amount_usdc: number;
+    currency: Currency;
+    status: InvoiceStatus;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    metadata_public: boolean;
+    consumption_type?: ConsumptionType;
+    replay_window_seconds?: number;
+    max_replays?: number;
+    created_at: string;
+    expires_at: string;
+}
+interface ConsumptionGuidance {
+    type: 'redeliverable' | 'consumable' | 'unknown';
+    replay_safe: boolean;
+    max_replays?: number | null;
+    replay_window_expires_at?: string;
+    guidance: string;
+}
+interface AgentGuidancePayload {
+    message: string;
+    next_step?: string;
+    persist: {
+        action: 'create' | 'update';
+        path: string;
+        required_fields: string[];
+        persist_full_response: boolean;
+    };
+}
+interface InvoicePublic {
+    id: string;
+    status: InvoiceStatus;
+    amount_usdc: number;
+    currency: Currency;
+    payment_address?: string;
+    solana_pay_url?: string;
+    gwop_pay_url?: string;
+    reference_pubkey?: string;
+    verify_payment_endpoint?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expires_at: string;
+    created_at: string;
+    paid_at?: string;
+    tx_signature?: string;
+    tx_url?: string;
+    merchant: {
+        name: string;
+        verified: boolean;
+    };
+    consumption: ConsumptionGuidance;
+    agent_guidance?: AgentGuidancePayload;
+}
+interface InvoiceListItem {
+    id: string;
+    status: InvoiceStatus;
+    amount_usdc: number;
+    currency: Currency;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expires_at: string;
+    created_at: string;
+    paid_at?: string;
+    tx_signature?: string;
+}
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface InvoiceListResponse {
+    invoices: InvoiceListItem[];
+    pagination: Pagination;
+}
+interface InvoiceListParams {
+    limit?: number;
+    offset?: number;
+    status?: InvoiceStatus;
+}
+interface InvoiceCancelResponse {
+    id: string;
+    status: 'CANCELED';
+    canceled_at: string;
+}
+interface InvoicePayRequest {
+    otp_code?: string;
+    otp_challenge_id?: string;
+}
+interface InvoicePayResponse {
+    id: string;
+    status: 'PAID';
+    tx_signature: string;
+    tx_url: string;
+    paid_at: string;
+    payment_intent_id: string;
+    consumption: ConsumptionGuidance;
+    agent_guidance?: AgentGuidancePayload;
+}
+interface VerifyPaymentRequest {
+    tx_signature: string;
+    payer_address?: string;
+}
+interface VerifyPaymentResponse {
+    id: string;
+    status: 'PAID';
+    tx_signature: string;
+    tx_url: string;
+    paid_at: string;
+    payer_address: string;
+    paid_amount: number;
+    consumption: ConsumptionGuidance;
+    agent_guidance?: AgentGuidancePayload;
+}
+type CheckoutWebhookEventType = 'invoice.paid' | 'invoice.expired' | 'invoice.canceled';
+interface CheckoutWebhookEventData {
+    invoice_id: string;
+    status: 'PAID' | 'EXPIRED' | 'CANCELED';
+    amount_usdc: number | string;
+    currency: Currency;
+    tx_signature?: string;
+    paid_at?: string;
+    payer_wallet?: string;
+}
+interface CheckoutWebhookEvent {
+    event_id: string;
+    event_type: CheckoutWebhookEventType;
+    event_version: number;
+    created_at: string;
+    data: CheckoutWebhookEventData;
+}
+
+type AuthMode = 'public' | 'merchant' | 'agent';
+interface RequestConfig {
+    auth: AuthMode;
+    path: string;
+    method: 'GET' | 'POST';
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    options?: PublicRequestOptions | AuthenticatedRequestOptions | IdempotentRequestOptions;
+}
+declare class CheckoutHttpClient {
+    private readonly baseUrl;
+    private merchantApiKey?;
+    private agentApiKey?;
+    constructor(config?: GwopCheckoutConfig);
+    setMerchantApiKey(apiKey: string): void;
+    setAgentApiKey(apiKey: string): void;
+    request<T>(config: RequestConfig): Promise<T>;
+    private resolveAuthKey;
+    private toApiError;
+}
+
+declare class InvoicesResource {
+    private readonly client;
+    constructor(client: CheckoutHttpClient);
+    create(body: CreateInvoiceRequest, options?: IdempotentRequestOptions): Promise<CreateInvoiceResponse>;
+    list(params?: InvoiceListParams, options?: AuthenticatedRequestOptions): Promise<InvoiceListResponse>;
+    retrieve(invoiceId: string, options?: PublicRequestOptions): Promise<InvoicePublic>;
+    cancel(invoiceId: string, options?: AuthenticatedRequestOptions): Promise<InvoiceCancelResponse>;
+    pay(invoiceId: string, body?: InvoicePayRequest, options?: AuthenticatedRequestOptions): Promise<InvoicePayResponse>;
+    verifyExternalPayment(invoiceId: string, body: VerifyPaymentRequest, options?: PublicRequestOptions): Promise<VerifyPaymentResponse>;
+}
+
+declare class MerchantsResource {
+    private readonly client;
+    constructor(client: CheckoutHttpClient);
+    getInitPreflight(options?: PublicRequestOptions): Promise<MerchantInitPreflight>;
+    init(body: MerchantInitRequest, options: RequiredIdempotencyRequestOptions): Promise<MerchantInitResponse>;
+    getStatus(options?: AuthenticatedRequestOptions): Promise<MerchantStatusResponse>;
+    updateSettings(body: MerchantSettingsUpdateRequestPublic, options?: AuthenticatedRequestOptions): Promise<MerchantProfilePublic>;
+    generateWebhookSecret(options?: AuthenticatedRequestOptions): Promise<WebhookSecretResponse>;
+}
+
+interface ConstructEventOptions {
+    tolerance?: number;
+}
+declare class Webhooks {
+    constructEvent(payload: string | Buffer, signature: string | undefined, secret: string, options?: ConstructEventOptions): CheckoutWebhookEvent;
+    generateTestSignature(payload: string, secret: string, timestamp?: number): string;
+    private parseSignatureHeader;
+    private secureCompare;
+}
+
+declare class GwopCheckoutError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly requestId?: string | undefined;
+    readonly raw?: unknown | undefined;
+    constructor(message: string, code: string, statusCode: number, details?: Record<string, unknown> | undefined, requestId?: string | undefined, raw?: unknown | undefined);
+}
+declare class AuthenticationError extends GwopCheckoutError {
+    constructor(message?: string, requestId?: string, raw?: unknown);
+}
+declare class InvalidRequestError extends GwopCheckoutError {
+    constructor(message: string, code?: string, details?: Record<string, unknown>, requestId?: string, raw?: unknown);
+}
+declare class NotFoundError extends GwopCheckoutError {
+    constructor(message?: string, code?: string, requestId?: string, raw?: unknown);
+}
+declare class RateLimitError extends GwopCheckoutError {
+    constructor(message?: string, retryAfterSeconds?: number, requestId?: string, raw?: unknown);
+}
+
+declare class GwopCheckout {
+    readonly merchants: MerchantsResource;
+    readonly invoices: InvoicesResource;
+    readonly webhooks: Webhooks;
+    private readonly client;
+    constructor(config?: GwopCheckoutConfig);
+    setMerchantApiKey(apiKey: string): void;
+    setAgentApiKey(apiKey: string): void;
+}
+
+export { type AgentGuidancePayload, type AuthenticatedRequestOptions, AuthenticationError, type CheckoutWebhookEvent, type CheckoutWebhookEventData, type CheckoutWebhookEventType, type ConsumptionGuidance, type ConsumptionType, type CreateInvoiceRequest, type CreateInvoiceResponse, type Currency, type ErrorResponse, type FieldRequirement, GwopCheckout, type GwopCheckoutConfig, GwopCheckoutError, type IdempotentRequestOptions, InvalidRequestError, type InvoiceCancelResponse, type InvoiceListItem, type InvoiceListParams, type InvoiceListResponse, type InvoicePayRequest, type InvoicePayResponse, type InvoicePublic, type InvoiceStatus, type MerchantCapabilities, type MerchantInitPreflight, type MerchantInitRequest, type MerchantInitResponse, type MerchantProfilePublic, type MerchantSettingsUpdateRequestPublic, type MerchantStatusResponse, NotFoundError, type Pagination, type PublicRequestOptions, RateLimitError, type RequiredIdempotencyRequestOptions, type VerifyPaymentRequest, type VerifyPaymentResponse, type WebhookSecretResponse };