kstablepay-rail-sdk 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# kstablepay-rail-sdk
+
+Node.js SDK for K-STable Pay onchain rail APIs.
+
+## Install
+
+```bash
+npm i kstablepay-rail-sdk
+```
+
+## Usage
+
+```ts
+import { createKstChainClient } from "kstablepay-rail-sdk";
+
+const kstchain = createKstChainClient({
+  baseUrl: process.env.PAY_API_BASE_URL!,
+  walletSecretKey: process.env.WALLET_SECRET_KEY!,
+  walletAccessKey: process.env.WALLET_ACCESS_KEY, // optional
+  timeoutMs: 10000,
+});
+
+const issued = await kstchain.signPayload({
+  orderId: "ord_20260321_0001",
+  merchantKey: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  payerAddress: "0xC8313324B6C16Cec8F410ebfE1b22Ff4f5d2DDC8",
+  currency: "KST",
+  amount: "1000000",
+});
+
+const latest = await kstchain.getSignPayload(issued.paymentKey);
+
+const authorized = await kstchain.authorize({
+  paymentKey: issued.paymentKey,
+  signature: "0x...",
+  payloadHash: latest.payloadHash,
+});
+
+const command = await kstchain.getCommand(authorized.commandId);
+console.log(command.status);
+```
+
+## API
+
+- `health()`
+- `ready()`
+- `signPayload(req, opts?)`
+- `getSignPayload(paymentKey, opts?)`
+- `authorize(req, opts?)`
+- `capture(req, opts?)`
+- `void(req, opts?)`
+- `refund(req, opts?)`
+- `settle(req, opts?)`
+- `getCommand(commandId, opts?)`
+- `confirm(req, opts?)`
+
+## Error handling
+
+SDK throws `KstApiError` for non-2xx or error envelope responses.
+
+```ts
+import { KstApiError } from "kstablepay-rail-sdk";
+
+try {
+  await kstchain.authorize({ paymentKey, signature });
+} catch (e) {
+  if (e instanceof KstApiError) {
+    console.error(e.status, e.code, e.message);
+  }
+}
+```
+
+## Notes
+
+- This SDK is intended for **server-side (Node >= 18)** usage.
+- Do not expose `walletSecretKey` in browser/frontend code.

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import type { CaptureRequest, ClientOptions, CommandData, ConfirmData, ConfirmRequest, HealthData, IssueSignPayloadRequest, ReadyData, RefundRequest, RequestOptions, SettleRequest, SignPayloadData, SubmitSignatureData, SubmitSignatureRequest, VoidRequest } from "./types.js";
+export interface KstChainClient {
+    health(): Promise<HealthData>;
+    ready(): Promise<ReadyData>;
+    signPayload(req: IssueSignPayloadRequest, opts?: RequestOptions): Promise<SignPayloadData>;
+    getSignPayload(paymentKey: string, opts?: RequestOptions): Promise<SignPayloadData>;
+    authorize(req: SubmitSignatureRequest, opts?: RequestOptions): Promise<SubmitSignatureData>;
+    capture(req: CaptureRequest, opts?: RequestOptions): Promise<CommandData>;
+    void(req: VoidRequest, opts?: RequestOptions): Promise<CommandData>;
+    refund(req: RefundRequest, opts?: RequestOptions): Promise<CommandData>;
+    settle(req: SettleRequest, opts?: RequestOptions): Promise<CommandData>;
+    getCommand(commandId: string, opts?: RequestOptions): Promise<CommandData>;
+    confirm(req: ConfirmRequest, opts?: RequestOptions): Promise<ConfirmData>;
+}
+export declare function createKstChainClient(options: ClientOptions): KstChainClient;

package/dist/client.js

@@ -0,0 +1,91 @@
+import { KstApiError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 10000;
+export function createKstChainClient(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const walletSecretKey = options.walletSecretKey?.trim();
+    const walletAccessKey = options.walletAccessKey?.trim();
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!walletSecretKey) {
+        throw new Error("walletSecretKey is required");
+    }
+    if (!fetchImpl) {
+        throw new Error("No fetch implementation available");
+    }
+    const defaultTimeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const call = async (method, path, body, opts) => {
+        const headers = {
+            "X-Wallet-Secret-Key": walletSecretKey,
+        };
+        if (walletAccessKey) {
+            headers["X-Wallet-Access-Key"] = walletAccessKey;
+        }
+        if (opts?.idempotencyKey) {
+            headers["Idempotency-Key"] = opts.idempotencyKey;
+        }
+        const timeoutMs = opts?.timeoutMs ?? defaultTimeoutMs;
+        const ac = new AbortController();
+        const timeout = setTimeout(() => ac.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(baseUrl + path, {
+                method,
+                headers: {
+                    ...headers,
+                    ...(body ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: mergeSignals(ac.signal, opts?.signal),
+            });
+            let parsed;
+            try {
+                parsed = await res.json();
+            }
+            catch {
+                throw new KstApiError(res.status, "INVALID_RESPONSE", "response is not valid json");
+            }
+            const envelope = parsed;
+            if (!envelope || typeof envelope !== "object" || !("success" in envelope)) {
+                throw new KstApiError(res.status, "INVALID_ENVELOPE", "response envelope is invalid", parsed);
+            }
+            if (!res.ok || envelope.success === false) {
+                const code = envelope?.error?.code ?? "REQUEST_FAILED";
+                const message = envelope?.error?.message ?? `request failed with status ${res.status}`;
+                throw new KstApiError(res.status, code, message, parsed);
+            }
+            return envelope.data;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+    return {
+        health: () => call("GET", "/healthz"),
+        ready: () => call("GET", "/readyz"),
+        signPayload: (req, opts) => call("POST", "/v1/onchain/sign-payload", req, opts),
+        getSignPayload: (paymentKey, opts) => call("GET", `/v1/onchain/sign-payloads/${encodeURIComponent(paymentKey)}`, undefined, opts),
+        authorize: (req, opts) => call("POST", "/v1/onchain/authorize", req, opts),
+        capture: (req, opts) => call("POST", "/v1/onchain/capture", req, opts),
+        void: (req, opts) => call("POST", "/v1/onchain/void", req, opts),
+        refund: (req, opts) => call("POST", "/v1/onchain/refund", req, opts),
+        settle: (req, opts) => call("POST", "/v1/onchain/settle", req, opts),
+        getCommand: (commandId, opts) => call("GET", `/v1/onchain/commands/${encodeURIComponent(commandId)}`, undefined, opts),
+        confirm: (req, opts) => call("POST", "/v1/onchain/confirm", req, opts),
+    };
+}
+function normalizeBaseUrl(baseUrl) {
+    const out = baseUrl.trim();
+    if (!out) {
+        throw new Error("baseUrl is required");
+    }
+    return out.endsWith("/") ? out.slice(0, -1) : out;
+}
+function mergeSignals(a, b) {
+    if (!b)
+        return a;
+    if (b.aborted)
+        return b;
+    const ac = new AbortController();
+    const abort = () => ac.abort();
+    a.addEventListener("abort", abort, { once: true });
+    b.addEventListener("abort", abort, { once: true });
+    return ac.signal;
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class KstApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly raw?: unknown;
+    constructor(status: number, code: string, message: string, raw?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class KstApiError extends Error {
+    status;
+    code;
+    raw;
+    constructor(status, code, message, raw) {
+        super(message);
+        this.name = "KstApiError";
+        this.status = status;
+        this.code = code;
+        this.raw = raw;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createKstChainClient } from "./client.js";
+export type { KstChainClient } from "./client.js";
+export { KstApiError } from "./errors.js";
+export type { AuthorizationPayload, CapturePayload, CaptureRequest, ClientOptions, CommandData, CommandStatus, CommandType, ConfirmData, ConfirmRequest, Envelope, ErrorEnvelope, HealthData, IssueSignPayloadRequest, ReadyData, RefundPayload, RefundRequest, RequestOptions, SettlePayload, SettleRequest, SignPayloadData, SignPayloadStatus, SubmitSignatureData, SubmitSignatureRequest, SuccessEnvelope, VoidPayload, VoidRequest, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createKstChainClient } from "./client.js";
+export { KstApiError } from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+export type CommandType = "authorize" | "capture" | "void" | "settle" | "refund";
+export type CommandStatus = "pending" | "processing" | "submitted" | "authorized_confirmed" | "succeeded" | "failed" | "dead_letter";
+export type SignPayloadStatus = "issued" | "submitted";
+export interface EnvelopeBase {
+    success: boolean;
+    timestamp: string;
+}
+export interface ErrorBody {
+    code: string;
+    message: string;
+}
+export interface SuccessEnvelope<T> extends EnvelopeBase {
+    success: true;
+    data: T;
+}
+export interface ErrorEnvelope extends EnvelopeBase {
+    success: false;
+    error: ErrorBody;
+}
+export type Envelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+export interface AuthorizationPayload {
+    paymentKey?: string;
+    paymentId: string;
+    merchantKey: string;
+    payerAddress: string;
+    tokenAddress: string;
+    amount: string;
+    nonce: number;
+    deadline: number;
+}
+export interface CapturePayload {
+    paymentId: string;
+}
+export interface VoidPayload {
+    paymentId: string;
+}
+export interface RefundPayload {
+    paymentId: string;
+    refundAmount: string;
+    refundDestination: string;
+}
+export interface SettlePayload {
+    paymentId: string;
+    merchantId?: string;
+    settlementMethod?: "stablecoin" | "fiat";
+    merchantWalletAddress: string;
+    tokenAddress: string;
+    grossAmount: string;
+    feeAmount: string;
+    netAmount: string;
+    fiatCurrency?: string;
+    fiatAmount?: string;
+    burnAmount?: string;
+}
+export interface CommandData {
+    id: string;
+    type: CommandType;
+    status: CommandStatus;
+    authorization?: AuthorizationPayload;
+    signature?: string;
+    payloadHash?: string;
+    capture?: CapturePayload;
+    void?: VoidPayload;
+    settle?: SettlePayload;
+    refund?: RefundPayload;
+    txHash?: string;
+    error?: string;
+    retryCount: number;
+    maxRetries: number;
+    nextAttemptAt?: string;
+    processingAt?: string;
+    submittedAt?: string;
+    deadLetterReason?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface IssueSignPayloadRequest {
+    orderId: string;
+    merchantKey: string;
+    payerAddress: string;
+    currency: "KST" | "USDC";
+    amount: string;
+    deadline?: number;
+}
+export interface SignPayloadData {
+    paymentKey: string;
+    paymentSessionId: string;
+    payloadHash: string;
+    payloadReady: boolean;
+    nonce: number;
+    deadline: number;
+    status: SignPayloadStatus;
+}
+export interface SubmitSignatureRequest {
+    paymentKey: string;
+    signature: string;
+    payloadHash?: string;
+}
+export interface SubmitSignatureData {
+    commandId: string;
+    paymentKey: string;
+    status: SignPayloadStatus;
+    command: CommandData;
+}
+export interface CaptureRequest {
+    requestId?: string;
+    paymentKey: string;
+}
+export interface VoidRequest {
+    requestId?: string;
+    paymentKey: string;
+}
+export interface RefundRequest {
+    requestId?: string;
+    paymentKey: string;
+    refundAmount: string;
+    refundDestination?: string;
+}
+export interface SettleRequest {
+    requestId?: string;
+    paymentKey: string;
+    settlementMethod?: "stablecoin" | "fiat";
+    merchantWalletAddress?: string;
+    tokenAddress?: string;
+    grossAmount?: string;
+    feeAmount?: string;
+    netAmount?: string;
+    fiatCurrency?: string;
+    fiatAmount?: string;
+    burnAmount?: string;
+    settlementDelayDays?: number;
+}
+export interface ConfirmRequest {
+    paymentKey: string;
+    orderId: string;
+    amount: string;
+}
+export interface ConfirmData {
+    paymentKey: string;
+    orderId: string;
+    amount: string;
+    commandId?: string;
+    commandStatus?: CommandStatus;
+    txHash?: string;
+    result: "success" | "failed";
+    reason?: string;
+}
+export interface HealthData {
+    status: string;
+}
+export interface ReadyData {
+    status: string;
+    chainId: number;
+    l1ChainId: number;
+    escrowContract: string;
+    dbHost?: string;
+    dbPort?: number;
+    dbName?: string;
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ClientOptions {
+    baseUrl: string;
+    walletSecretKey: string;
+    walletAccessKey?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "kstablepay-rail-sdk",
+  "version": "0.1.0",
+  "description": "Node SDK for K-STable Pay onchain rail APIs",
+  "license": "MIT",
+  "author": "K-STable Pay",
+  "homepage": "https://github.com/moonyaeyoon/k-stable-pay",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moonyaeyoon/k-stable-pay.git",
+    "directory": "infra/packages/kstchain-sdk"
+  },
+  "keywords": [
+    "kstable",
+    "pay",
+    "wallet",
+    "sdk",
+    "onchain",
+    "rail"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}