@mooj/sdk 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @mooj/sdk
+
+The official Mooj SDK. Issue capped virtual cards and let your agent complete real checkouts. Card controls, 3DS, and fraud caps are handled for you.
+
+## Install
+
+```
+npm install @mooj/sdk
+```
+
+Requires Node 18+ (uses the built-in `fetch`).
+
+## Quickstart
+
+```ts
+import { Mooj } from '@mooj/sdk';
+
+const mooj = new Mooj(process.env.MOOJ_API_KEY!); // key looks like mk_live_...
+
+// Issue a single-use card capped at $20
+const card = await mooj.cards.create({
+  amount: 20,
+  merchant: 'namecheap',
+  single_use: true,
+});
+console.log(card.id, card.last4, card.spend_limit);
+```
+
+Get your API key from the Mooj console (Developer -> API keys). Keep it server-side; never commit it.
+
+## Tools
+
+### Cards
+
+```ts
+const card = await mooj.cards.create({ amount: 20, merchant: 'namecheap', single_use: true });
+const full = await mooj.cards.reveal(card.id);   // { number, cvc, exp, ... } — use at the moment of purchase
+const closed = await mooj.cards.close(card.id);  // release the unused reserve back to your wallet
+```
+
+### Spend status
+
+```ts
+const spend = await mooj.spend.get(card.spend_request_id!);
+// spend.status: 'not_started' | 'authorized' | 'cleared' | 'declined'
+```
+
+### Checkout (Mooj drives the buy)
+
+```ts
+const run = await mooj.checkout.create({
+  task: 'buy the domain mooj.click for 1 year',
+  merchant: 'namecheap',
+  amount: 20,
+  confirm_pay: false, // dry run: stops at the final review. true = pay up to the cap.
+});
+
+// poll until it finishes
+let status = await mooj.checkout.get(run.checkout_id);
+// status.status: 'queued' | 'running' | 'awaiting_approval' | 'needs_login' | 'submitted' | 'blocked'
+```
+
+### Connections (login-gated merchants)
+
+```ts
+const conn = await mooj.connections.create({ merchant: 'namecheap', user_ref: 'user-123' });
+// open conn.connect_url so the user signs in, then:
+await mooj.connections.complete(conn.connection_id);
+// now pass connection_id to checkout.create to run signed-in
+```
+
+## Errors
+
+Any non-2xx response throws a `MoojError` with the HTTP status, the Mooj error code, and the request id.
+
+```ts
+import { Mooj, MoojError } from '@mooj/sdk';
+
+try {
+  await mooj.cards.create({ amount: 999999, merchant: 'namecheap' });
+} catch (e) {
+  if (e instanceof MoojError) {
+    console.error(e.status, e.code, e.requestId, e.message);
+    // e.g. 402 insufficient_funds
+  }
+}
+```
+
+## Configuration
+
+```ts
+new Mooj({
+  apiKey: process.env.MOOJ_API_KEY!,
+  baseUrl: 'https://mooj-api-277196974190.us-central1.run.app', // optional override
+});
+```
+
+## Docs
+
+Full API reference: https://storage.googleapis.com/mooj-docs/index.html

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @mooj/sdk — the official Mooj SDK.
+ *
+ * A thin, typed wrapper over the Mooj REST API (v1). Issue capped virtual cards and let your
+ * agent complete real checkouts; card controls, 3DS, and fraud caps are handled for you.
+ *
+ *   import { Mooj } from '@mooj/sdk';
+ *   const mooj = new Mooj(process.env.MOOJ_API_KEY!);
+ *   const card = await mooj.cards.create({ amount: 20, merchant: 'namecheap', single_use: true });
+ */
+export interface MoojOptions {
+    /** Your secret API key, e.g. "mk_live_...". Create one in the Mooj console. */
+    apiKey: string;
+    /** Override the API base URL (defaults to the live Mooj gateway). */
+    baseUrl?: string;
+    /** Provide a custom fetch implementation (defaults to global fetch, Node 18+). */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx response. Carries the HTTP status, the Mooj error code, and the request id. */
+export declare class MoojError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+export interface Card {
+    id: string;
+    brand: string;
+    last4: string;
+    exp_month: number;
+    exp_year: number;
+    spend_limit: number;
+    single_use: boolean;
+    status: string;
+    spend_request_id: string | null;
+}
+export interface RevealedCard {
+    id: string;
+    last4: string;
+    number: string;
+    number_formatted: string;
+    cvc: string;
+    exp: string;
+}
+export interface ClosedCard {
+    id: string;
+    status: string;
+    released_display: string;
+    available_to_issue_display: string;
+}
+export interface SpendStatus {
+    spend_request_id: string;
+    merchant: string;
+    decision: string;
+    status: 'not_started' | 'authorized' | 'cleared' | 'declined' | string;
+    settled: boolean;
+    amount: number;
+}
+export interface Checkout {
+    checkout_id: string;
+    status: 'queued' | 'running' | 'awaiting_approval' | 'needs_login' | 'submitted' | 'blocked' | string;
+    poll?: string;
+    task?: string;
+    merchant?: string;
+    amount?: number;
+    card_last4?: string;
+    review_total?: number;
+    order_id?: string | null;
+    order_total?: number | null;
+    needs_login?: boolean;
+    error_reason?: string | null;
+}
+export interface Connection {
+    connection_id: string;
+    connect_url?: string;
+    status: 'pending' | 'connected' | string;
+}
+export interface CreateCardParams {
+    /** Spend cap in US dollars. Per-card ceiling is $5,000. */
+    amount: number;
+    merchant: string;
+    /** Default true. Auto-freezes after the first charge. */
+    single_use?: boolean;
+    network?: 'auto' | 'visa' | 'mastercard';
+    card_name?: string;
+}
+export interface CreateCheckoutParams {
+    task: string;
+    merchant: string;
+    /** Maximum USD to spend (becomes the card cap). */
+    amount: number;
+    /** false (default) = dry run, stops at review. true = pay autonomously up to the cap. */
+    confirm_pay?: boolean;
+    connection_id?: string;
+    card_holder_name?: string;
+    start_url?: string;
+}
+export interface CreateConnectionParams {
+    merchant: string;
+    user_ref?: string;
+}
+export declare class Mooj {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly _fetch;
+    constructor(options: MoojOptions | string);
+    private request;
+    /** Virtual cards: issue, reveal the PAN, and close. */
+    readonly cards: {
+        create: (params: CreateCardParams) => Promise<Card>;
+        reveal: (id: string) => Promise<RevealedCard>;
+        close: (id: string) => Promise<ClosedCard>;
+    };
+    /** Spend status for a card issued with cards.create (pass the spend_request_id). */
+    readonly spend: {
+        get: (spendRequestId: string) => Promise<SpendStatus>;
+    };
+    /** Let Mooj drive a full checkout. create() is async; poll with get(). */
+    readonly checkout: {
+        create: (params: CreateCheckoutParams) => Promise<Checkout>;
+        get: (checkoutId: string) => Promise<Checkout>;
+    };
+    /** Reusable merchant logins for login-gated stores. */
+    readonly connections: {
+        create: (params: CreateConnectionParams) => Promise<Connection>;
+        complete: (id: string) => Promise<Connection>;
+        list: () => Promise<Connection[] | {
+            connections?: Connection[];
+        }>;
+        get: (id: string) => Promise<Connection>;
+    };
+}
+export default Mooj;

package/dist/index.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * @mooj/sdk — the official Mooj SDK.
+ *
+ * A thin, typed wrapper over the Mooj REST API (v1). Issue capped virtual cards and let your
+ * agent complete real checkouts; card controls, 3DS, and fraud caps are handled for you.
+ *
+ *   import { Mooj } from '@mooj/sdk';
+ *   const mooj = new Mooj(process.env.MOOJ_API_KEY!);
+ *   const card = await mooj.cards.create({ amount: 20, merchant: 'namecheap', single_use: true });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mooj = exports.MoojError = void 0;
+const DEFAULT_BASE_URL = 'https://mooj-api-277196974190.us-central1.run.app';
+/** Thrown on any non-2xx response. Carries the HTTP status, the Mooj error code, and the request id. */
+class MoojError extends Error {
+    constructor(message, status, code, requestId) {
+        super(message);
+        this.name = 'MoojError';
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+exports.MoojError = MoojError;
+class Mooj {
+    constructor(options) {
+        /** Virtual cards: issue, reveal the PAN, and close. */
+        this.cards = {
+            create: (params) => this.request('POST', '/v1/cards', params),
+            reveal: (id) => this.request('GET', `/v1/cards/${encodeURIComponent(id)}`),
+            close: (id) => this.request('POST', `/v1/cards/${encodeURIComponent(id)}/close`),
+        };
+        /** Spend status for a card issued with cards.create (pass the spend_request_id). */
+        this.spend = {
+            get: (spendRequestId) => this.request('GET', `/v1/spend/${encodeURIComponent(spendRequestId)}`),
+        };
+        /** Let Mooj drive a full checkout. create() is async; poll with get(). */
+        this.checkout = {
+            create: (params) => this.request('POST', '/v1/checkout', params),
+            get: (checkoutId) => this.request('GET', `/v1/checkout/${encodeURIComponent(checkoutId)}`),
+        };
+        /** Reusable merchant logins for login-gated stores. */
+        this.connections = {
+            create: (params) => this.request('POST', '/v1/connections', params),
+            complete: (id) => this.request('POST', `/v1/connections/${encodeURIComponent(id)}/complete`),
+            list: () => this.request('GET', '/v1/connections'),
+            get: (id) => this.request('GET', `/v1/connections/${encodeURIComponent(id)}`),
+        };
+        const o = typeof options === 'string' ? { apiKey: options } : options;
+        if (!o || !o.apiKey)
+            throw new Error('Mooj: apiKey is required');
+        this.apiKey = o.apiKey;
+        this.baseUrl = (o.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+        const f = o.fetch || globalThis.fetch;
+        if (!f)
+            throw new Error('Mooj: no fetch available. Use Node 18+ or pass options.fetch.');
+        this._fetch = f;
+    }
+    async request(method, path, body) {
+        const res = await this._fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const requestId = res.headers.get('X-Mooj-Request-Id') || undefined;
+        const text = await res.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!res.ok) {
+            const d = (data ?? {});
+            const message = d.message || d.error || `Mooj API error ${res.status}`;
+            throw new MoojError(message, res.status, d.error, d.request_id || requestId);
+        }
+        return data;
+    }
+}
+exports.Mooj = Mooj;
+exports.default = Mooj;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mooj/sdk",
+  "version": "0.1.0",
+  "description": "Official Mooj SDK. Issue capped virtual cards and let your agent complete real checkouts. 3DS handled.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mooj",
+    "payments",
+    "ai-agents",
+    "virtual-cards",
+    "checkout",
+    "3ds"
+  ],
+  "author": "Mooj",
+  "license": "MIT",
+  "homepage": "https://storage.googleapis.com/mooj-docs/index.html",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  }
+}