@sneekin/sdk 0.3.2 → 1.1.0

package/dist/pay/index.js

@@ -0,0 +1,192 @@
+// src/core/client.ts
+var SneekApiError = class extends Error {
+  constructor(status, type, title, detail) {
+    super(`${title}${detail ? `: ${detail}` : ""} [${status}]`);
+    this.status = status;
+    this.type = type;
+    this.title = title;
+    this.detail = detail;
+    this.name = "SneekApiError";
+  }
+  status;
+  type;
+  title;
+  detail;
+};
+var SneekClient = class {
+  apiUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  retryBaseMs;
+  constructor(options) {
+    if (!options.apiUrl) throw new Error("apiUrl is required");
+    if (!options.apiKey) throw new Error("apiKey is required");
+    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.retryBaseMs = options.retryBaseMs ?? 200;
+  }
+  async request(method, path, body, extraHeaders) {
+    const raw = body === void 0 ? void 0 : JSON.stringify(body);
+    let attempt = 0;
+    let lastError;
+    for (; ; ) {
+      try {
+        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+          method,
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+            ...extraHeaders ?? {}
+          },
+          body: raw
+        });
+        const text = await response.text();
+        const parsed = text ? parseJson(text) : void 0;
+        if (!response.ok) {
+          const problem = asProblem(parsed);
+          const error = new SneekApiError(
+            response.status,
+            problem.type ?? "about:blank",
+            problem.title ?? response.statusText,
+            problem.detail
+          );
+          if (response.status >= 500 && attempt < this.maxRetries) {
+            lastError = error;
+            await this.backoff(attempt++);
+            continue;
+          }
+          throw error;
+        }
+        return parsed;
+      } catch (error) {
+        if (error instanceof SneekApiError) throw error;
+        if (attempt < this.maxRetries) {
+          lastError = error;
+          await this.backoff(attempt++);
+          continue;
+        }
+        throw lastError ?? error;
+      }
+    }
+  }
+  backoff(attempt) {
+    return new Promise((resolve) => setTimeout(resolve, this.retryBaseMs * 2 ** attempt));
+  }
+};
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function asProblem(value) {
+  if (typeof value !== "object" || value === null) return {};
+  const problem = value;
+  return {
+    type: typeof problem.type === "string" ? problem.type : void 0,
+    title: typeof problem.title === "string" ? problem.title : void 0,
+    detail: typeof problem.detail === "string" ? problem.detail : void 0
+  };
+}
+
+// src/core/derive-keys.ts
+import { hkdfSync } from "crypto";
+var KEY_LABELS = {
+  qrSigningKey: "sneek-qr-v1",
+  webhookSigningKey: "sneek-webhook-v1",
+  proofKey: "sneek-proof-v1"
+};
+function deriveKeys(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new TypeError("apiKey must be a nonempty string");
+  }
+  const inputKeyMaterial = Buffer.from(apiKey, "utf8");
+  const derive = (label) => Buffer.from(
+    hkdfSync("sha256", inputKeyMaterial, Buffer.alloc(0), label, 32)
+  );
+  return {
+    qrSigningKey: derive(KEY_LABELS.qrSigningKey),
+    webhookSigningKey: derive(KEY_LABELS.webhookSigningKey),
+    proofKey: derive(KEY_LABELS.proofKey)
+  };
+}
+
+// src/pay/payments.ts
+var SneekPayClient = class {
+  client;
+  orders;
+  constructor(options) {
+    this.client = new SneekClient(options);
+    this.orders = new OrdersClient(this);
+  }
+  /** @internal */
+  async request(method, path, body, extraHeaders) {
+    return this.client.request(method, path, body, extraHeaders);
+  }
+  /**
+   * Verify the checkout handler payload and settle the order. Idempotent:
+   * calling it twice with the same pair returns the same result.
+   */
+  verify(input) {
+    return this.request("POST", "/api/payments/verify", {
+      order_id: input.orderId,
+      payment_id: input.paymentId,
+      signature: input.signature
+    });
+  }
+};
+var OrdersClient = class {
+  constructor(pay) {
+    this.pay = pay;
+  }
+  pay;
+  create(input) {
+    const payload = {
+      amount: String(input.amount),
+      currency: input.currency ?? "INR"
+    };
+    if (input.receipt !== void 0) payload.receipt = input.receipt;
+    if (input.clientRef !== void 0) payload.client_ref = input.clientRef;
+    if (input.notes !== void 0) payload.notes = input.notes;
+    if (input.settleAfter !== void 0) {
+      payload.settle_after = input.settleAfter instanceof Date ? input.settleAfter.toISOString() : input.settleAfter;
+    }
+    const headers = input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0;
+    return this.pay.request(
+      "POST",
+      "/api/payments/orders",
+      payload,
+      headers
+    );
+  }
+  get(id) {
+    return this.pay.request(
+      "GET",
+      `/api/payments/orders/${encodeURIComponent(id)}`
+    );
+  }
+  /**
+   * The event moved: hold the organizer share until the new end plus the
+   * platform refund window. Only works while the payout is still on hold;
+   * a released payout answers 409.
+   */
+  reschedule(id, input) {
+    const settleAfter = input.settleAfter instanceof Date ? input.settleAfter.toISOString() : input.settleAfter;
+    return this.pay.request(
+      "PATCH",
+      `/api/payments/orders/${encodeURIComponent(id)}/settlement`,
+      { settle_after: settleAfter }
+    );
+  }
+};
+export {
+  OrdersClient,
+  SneekApiError,
+  SneekClient,
+  SneekPayClient,
+  deriveKeys
+};

package/dist/pay/payments.d.ts

@@ -0,0 +1,90 @@
+import type { CreateOrderResponse, GetOrderResponse, Settlement as GeneratedSettlement, VerifyPayment, VerifyPaymentResponse } from '../core/generated/api.js';
+import { SneekApiError, type SneekClientOptions } from '../core/index.js';
+/**
+ * Options for {@link SneekPayClient}.
+ */
+export type SneekPayClientOptions = SneekClientOptions;
+export type PaymentStatus = GetOrderResponse['status'];
+export interface CreateOrderInput {
+    /** Amount in MAJOR units (rupees), e.g. `499` or `'499.50'`. Max 2 decimals. */
+    amount: number | string;
+    /** ISO-4217 code. Defaults to `INR`. */
+    currency?: string;
+    /** Your own reference. Unique per application; a repeat returns the original order. */
+    receipt?: string;
+    /** Your correlation id, echoed back on reads. */
+    clientRef?: string;
+    /** Non-PII metadata forwarded to the gateway. */
+    notes?: Record<string, unknown>;
+    /**
+     * When your event ends. The organizer share stays on hold until this moment
+     * plus the platform refund window, so buyer refunds can be reversed from it.
+     * Omit to hold for the refund window from payment only.
+     */
+    settleAfter?: string | Date;
+    /** Sent as the `Idempotency-Key` header so a retried call cannot double-charge. */
+    idempotencyKey?: string;
+}
+export type SettlementStatus = GeneratedSettlement['status'];
+/** Where the organizer share of a partner payment stands. Amounts in major units. */
+export type Settlement = GeneratedSettlement;
+export type CreateOrderResult = CreateOrderResponse;
+export type PaymentOrder = GetOrderResponse;
+/** Exactly the three fields the browser checkout handler hands back. */
+export interface VerifyInput {
+    orderId: VerifyPayment['order_id'];
+    paymentId: VerifyPayment['payment_id'];
+    signature: VerifyPayment['signature'];
+}
+export type VerifyResult = VerifyPaymentResponse;
+/**
+ * Accept payments with only your Sneek application API key.
+ *
+ * Sneek holds the payment-gateway merchant credentials centrally, exactly as it
+ * holds the SMS/WhatsApp/email provider credentials centrally. Your
+ * server never stores a gateway secret; the only gateway value you ever receive
+ * is `key_id`, the PUBLIC key the browser checkout widget needs.
+ *
+ * @example
+ * const pay = new SneekPayClient({ apiUrl: 'https://sneek.in', apiKey });
+ *
+ * // 1. Server: create the order.
+ * const order = await pay.orders.create({ amount: '499.00', receipt: 'inv-1001' });
+ *
+ * // 2. Browser: open checkout with order.key_id and order.provider_order_id.
+ *
+ * // 3. Server: verify what the browser handler returned.
+ * const result = await pay.verify({
+ *     orderId: handler.razorpay_order_id,
+ *     paymentId: handler.razorpay_payment_id,
+ *     signature: handler.razorpay_signature,
+ * });
+ */
+export declare class SneekPayClient {
+    private readonly client;
+    readonly orders: OrdersClient;
+    constructor(options: SneekPayClientOptions);
+    /** @internal */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /**
+     * Verify the checkout handler payload and settle the order. Idempotent:
+     * calling it twice with the same pair returns the same result.
+     */
+    verify(input: VerifyInput): Promise<VerifyResult>;
+}
+export declare class OrdersClient {
+    private readonly pay;
+    constructor(pay: SneekPayClient);
+    create(input: CreateOrderInput): Promise<CreateOrderResult>;
+    get(id: string): Promise<PaymentOrder>;
+    /**
+     * The event moved: hold the organizer share until the new end plus the
+     * platform refund window. Only works while the payout is still on hold;
+     * a released payout answers 409.
+     */
+    reschedule(id: string, input: {
+        settleAfter: string | Date;
+    }): Promise<PaymentOrder>;
+}
+export { SneekApiError };
+export default SneekPayClient;

package/dist/verify/approval-store.d.ts

@@ -0,0 +1,22 @@
+export interface SneekQrSession {
+    ref: string;
+    applicationId: string;
+    origin: string;
+    bindingProofHash: string;
+    expiresAt: number;
+    requestId?: string;
+}
+export interface SneekQrApprovalEvent {
+    type: 'qr.approved';
+    applicationId: string;
+    ref: string;
+    requestId: string;
+}
+export interface SneekApprovalStore {
+    createQrSession(session: SneekQrSession): Promise<void>;
+    /** Atomically attach only the first matching approval to a live QR session. */
+    recordQrApproval(event: SneekQrApprovalEvent, now: number): Promise<'recorded' | 'duplicate' | 'missing'>;
+    readQrSession(ref: string): Promise<SneekQrSession | null>;
+    /** Atomically claim a token jti until its exp time; false means replay. */
+    claimJti(jti: string, expiresAt: number): Promise<boolean>;
+}

package/dist/verify/auth-schema.d.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+export declare const QrWebhookEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"qr.approved">;
+    applicationId: z.ZodString;
+    ref: z.ZodString;
+    requestId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "qr.approved";
+    requestId: string;
+    ref: string;
+    applicationId: string;
+}, {
+    type: "qr.approved";
+    requestId: string;
+    ref: string;
+    applicationId: string;
+}>;
+export declare const SneekVerifyActionSchema: z.ZodUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"config">;
+}, "strict", z.ZodTypeAny, {
+    action: "config";
+}, {
+    action: "config";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"request">;
+    identifier: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "request";
+    identifier: string;
+}, {
+    action: "request";
+    identifier: string;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"switch">;
+    requestId: z.ZodString;
+    channel: z.ZodEnum<["sms", "whatsapp", "email", "push"]>;
+    proof: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "switch";
+    requestId: string;
+    channel: "email" | "sms" | "whatsapp" | "push";
+    proof: string;
+}, {
+    action: "switch";
+    requestId: string;
+    channel: "email" | "sms" | "whatsapp" | "push";
+    proof: string;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"verify">;
+    requestId: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    proof: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "verify";
+    requestId: string;
+    proof: string;
+    code?: string | undefined;
+}, {
+    action: "verify";
+    requestId: string;
+    proof: string;
+    code?: string | undefined;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"verify">;
+    requestId: z.ZodString;
+    ref: z.ZodString;
+    bindingProof: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "verify";
+    requestId: string;
+    ref: string;
+    bindingProof: string;
+}, {
+    action: "verify";
+    requestId: string;
+    ref: string;
+    bindingProof: string;
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"create">;
+}, "strict", z.ZodTypeAny, {
+    action: "create";
+}, {
+    action: "create";
+}>, z.ZodObject<{
+    action: z.ZodLiteral<"status">;
+    ref: z.ZodString;
+    bindingProof: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "status";
+    ref: string;
+    bindingProof: string;
+}, {
+    action: "status";
+    ref: string;
+    bindingProof: string;
+}>]>;
+export type SneekVerifyAction = z.infer<typeof SneekVerifyActionSchema>;

package/dist/verify/handler.d.ts

@@ -0,0 +1,41 @@
+import type { SneekApprovalStore } from './approval-store.js';
+export interface SneekVerifyHandlerOptions {
+    apiUrl: string;
+    apiKey: string;
+    allowedOrigins: string[];
+    approvalStore: SneekApprovalStore;
+    onVerified: (result: {
+        identifier: string;
+        kind: 'email' | 'mobile';
+        method: string;
+        verifiedAt: string;
+        requestId: string;
+    }) => void | Promise<void>;
+    fetch?: typeof fetch;
+}
+export declare class SneekVerifyHandler {
+    private readonly client;
+    private readonly allowedOrigins;
+    private readonly keys;
+    private readonly approvalStore;
+    private readonly onVerified;
+    private readonly jwksByIssuer;
+    constructor(options: SneekVerifyHandlerOptions);
+    handle(request: Request): Promise<Response>;
+    handleWebhook(request: Request): Promise<Response>;
+    private getAllowedOrigin;
+    private config;
+    private startVerification;
+    private switchVerification;
+    private verify;
+    private verifiedClaims;
+    private startResponse;
+    private createProof;
+    private isValidProof;
+    private createQr;
+    private qrStatus;
+    private qrSession;
+    private partnerConfig;
+    private isValidWebhookSignature;
+    private hash;
+}