@duabalabs/dps-client 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @duabalabs/dps-client
+
+Tiny typed client for the DPS unified checkout / commerce orchestration cloud functions.
+
+Two consumption modes:
+
+```ts
+// 1) Browser (uses Parse JS SDK, public app id + js key only)
+import Parse from "parse";
+import { createDpsClient } from "@duabalabs/dps-client";
+
+Parse.initialize(process.env.NEXT_PUBLIC_DPS_APP_ID!, process.env.NEXT_PUBLIC_DPS_JS_KEY!);
+Parse.serverURL = process.env.NEXT_PUBLIC_DPS_SERVER_URL!;
+
+const dps = createDpsClient({ Parse });
+const session = await dps.createCheckout({
+  appId: "sellub:store-123",
+  storeId: "store-123",
+  flow: "vendure",
+  channelToken: "abc...",
+  customer: { email: "shopper@example.com" },
+  currency: "GHS",
+  lineItems: [{ productVariantId: "42", name: "T-shirt", quantity: 1, unitPrice: 50 }],
+  callbackUrl: "https://shop.example.com/checkout/return",
+});
+window.location.href = session.checkoutUrl;
+```
+
+```ts
+// 2) Server (uses fetch + master key — never ship master key to the browser)
+import { createDpsServerClient } from "@duabalabs/dps-client";
+
+const dps = createDpsServerClient({
+  serverUrl: process.env.DPS_PARSE_URL!,        // e.g. https://dps.example.com/parse
+  appId: process.env.DPS_APP_ID!,
+  masterKey: process.env.DPS_MASTER_KEY!,
+});
+
+const session = await dps.createCheckout({ ... });
+```
+
+Method surface is identical. Returns identical shapes.
+
+## Methods
+
+| Method | Cloud function |
+| ------ | -------------- |
+| `createCheckout(input)` | `dps_checkout_create` |
+| `getCheckout(checkoutId)` | `dps_checkout_get` |
+| `cancelCheckout(checkoutId)` | `dps_checkout_cancel` |
+| `getOrder(orderId)` | `dps_orders_get` |
+| `listOrders(input)` | `dps_orders_list` |
+| `verifyPayment(reference)` | `dps_payments_verify` |
+
+## Generic by design
+
+`appId` is opaque (any app picks its own). `flow` is `"vendure"` or `"direct"`. App-specific concerns (donation `campaignId`, subscription `paystackPlanCode`, shipment payload, etc.) live in `metadata`/`paystackPlanCode`/`splitConfig` and are forwarded to the orchestrator.

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @duabalabs/dps-client — typed client for DPS unified checkout cloud functions.
+ *
+ * Two consumption modes:
+ *
+ *   1. Browser / public clients (uses Parse JS SDK + a JS key):
+ *        const dps = createDpsClient({ Parse });
+ *        await dps.createCheckout({ ... });
+ *
+ *   2. Server-side / trusted callers (uses fetch + master key — never ship
+ *      master key to the browser):
+ *        const dps = createDpsServerClient({
+ *          serverUrl: process.env.DPS_PARSE_URL,
+ *          appId: process.env.DPS_APP_ID,
+ *          masterKey: process.env.DPS_MASTER_KEY,
+ *        });
+ *        await dps.createCheckout({ ... });
+ *
+ * Both expose the same method surface and the same response types.
+ */
+export type CheckoutFlow = "vendure" | "direct";
+export type CheckoutStatus = "pending" | "awaiting_payment" | "paid" | "fulfilled" | "cancelled" | "failed" | "refunded";
+export type OrderStatus = CheckoutStatus;
+export interface CheckoutCustomer {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    parseUserId?: string;
+    vendureCustomerId?: string;
+}
+export interface CheckoutLineItem {
+    productVariantId?: string;
+    sku?: string;
+    name: string;
+    quantity: number;
+    unitPrice: number;
+    metadata?: Record<string, unknown>;
+}
+export interface PaystackSplitConfig {
+    type: "percentage" | "flat";
+    bearer?: "account" | "subaccount" | "all-proportional" | "all";
+    subaccounts: Array<{
+        subaccountCode: string;
+        share: number;
+    }>;
+}
+export interface CreateCheckoutInput {
+    appId: string;
+    storeId: string;
+    flow: CheckoutFlow;
+    channelToken?: string;
+    customer: CheckoutCustomer;
+    currency: string;
+    amount?: number;
+    lineItems?: CheckoutLineItem[];
+    metadata?: Record<string, unknown>;
+    callbackUrl?: string;
+    splitConfig?: PaystackSplitConfig;
+    paystackPlanCode?: string;
+    referencePrefix?: string;
+}
+export interface CheckoutSession {
+    checkoutId: string;
+    orderId: string;
+    paymentReference: string;
+    checkoutUrl: string;
+    accessCode?: string;
+    status: CheckoutStatus;
+    appId: string;
+    flow: CheckoutFlow;
+    storeId: string;
+    amount: number;
+    currency: string;
+    expiresAt?: string;
+}
+export interface OrderRecord {
+    id: string;
+    appId: string;
+    storeId: string;
+    flow: CheckoutFlow;
+    status: OrderStatus;
+    amount: number;
+    currency: string;
+    vendureOrderId?: string;
+    vendureOrderCode?: string;
+    channelToken?: string;
+    customerEmail: string;
+    userId?: string;
+    lineItems?: CheckoutLineItem[];
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListOrdersInput {
+    storeId: string;
+    appId?: string;
+    flow?: CheckoutFlow;
+    limit?: number;
+    skip?: number;
+}
+export interface PaymentVerification {
+    status: "success" | "failed" | "abandoned" | "pending" | string;
+    reference: string;
+    amount: number;
+    currency: string;
+    raw: Record<string, unknown>;
+}
+export interface SubscriptionStatus {
+    active: boolean;
+    tier: string | null;
+    expiresAt: string | null;
+    orderId: string | null;
+}
+export interface DpsClient {
+    createCheckout(input: CreateCheckoutInput): Promise<CheckoutSession>;
+    getCheckout(checkoutId: string): Promise<CheckoutSession | null>;
+    cancelCheckout(checkoutId: string): Promise<CheckoutSession | null>;
+    getOrder(orderId: string): Promise<OrderRecord | null>;
+    listOrders(input: ListOrdersInput): Promise<OrderRecord[]>;
+    verifyPayment(reference: string): Promise<PaymentVerification>;
+    checkSubscription(input: {
+        appId: string;
+        email: string;
+    }): Promise<SubscriptionStatus>;
+}
+export interface ParseLike {
+    Cloud: {
+        run: (name: string, params?: Record<string, unknown>) => Promise<unknown>;
+    };
+}
+export declare function createDpsClient(opts: {
+    Parse: ParseLike;
+}): DpsClient;
+export interface ServerClientOptions {
+    serverUrl: string;
+    appId: string;
+    masterKey: string;
+    /** Optional fetch impl (defaults to globalThis.fetch). */
+    fetch?: typeof fetch;
+}
+export declare function createDpsServerClient(opts: ServerClientOptions): DpsClient;
+export { withTenant, type TenantConfig, type TenantClient, type DonationCheckoutInput, type SubscriptionCheckoutInput, type InvoiceCheckoutInput, type ProductCheckoutInput, } from "./tenant";

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * @duabalabs/dps-client — typed client for DPS unified checkout cloud functions.
+ *
+ * Two consumption modes:
+ *
+ *   1. Browser / public clients (uses Parse JS SDK + a JS key):
+ *        const dps = createDpsClient({ Parse });
+ *        await dps.createCheckout({ ... });
+ *
+ *   2. Server-side / trusted callers (uses fetch + master key — never ship
+ *      master key to the browser):
+ *        const dps = createDpsServerClient({
+ *          serverUrl: process.env.DPS_PARSE_URL,
+ *          appId: process.env.DPS_APP_ID,
+ *          masterKey: process.env.DPS_MASTER_KEY,
+ *        });
+ *        await dps.createCheckout({ ... });
+ *
+ * Both expose the same method surface and the same response types.
+ */
+function unwrap(res) {
+    if (res &&
+        typeof res === "object" &&
+        "data" in res) {
+        return res.data;
+    }
+    return res;
+}
+export function createDpsClient(opts) {
+    const { Parse } = opts;
+    const run = async (name, params) => {
+        const res = (await Parse.Cloud.run(name, params));
+        return unwrap(res);
+    };
+    return {
+        createCheckout: (input) => run("dps_checkout_create", input),
+        getCheckout: (checkoutId) => run("dps_checkout_get", { checkoutId }),
+        cancelCheckout: (checkoutId) => run("dps_checkout_cancel", { checkoutId }),
+        getOrder: (orderId) => run("dps_orders_get", { orderId }),
+        listOrders: (input) => run("dps_orders_list", input),
+        verifyPayment: (reference) => run("dps_payments_verify", { reference }), checkSubscription: (input) => run("dps_subscriptions_check", input),
+    };
+}
+export function createDpsServerClient(opts) {
+    const fetchImpl = opts.fetch || globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("createDpsServerClient: no fetch implementation available. Pass `fetch` explicitly.");
+    }
+    const baseUrl = opts.serverUrl.replace(/\/$/, "");
+    const run = async (name, params = {}) => {
+        const res = await fetchImpl(`${baseUrl}/functions/${name}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Parse-Application-Id": opts.appId,
+                "X-Parse-Master-Key": opts.masterKey,
+            },
+            body: JSON.stringify(params),
+        });
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok || (json && "error" in json && json.error)) {
+            const msg = json?.error || `DPS ${name} failed (${res.status})`;
+            throw new Error(`@duabalabs/dps-client: ${msg}`);
+        }
+        return unwrap(json?.result);
+    };
+    return {
+        createCheckout: (input) => run("dps_checkout_create", input),
+        getCheckout: (checkoutId) => run("dps_checkout_get", { checkoutId }),
+        cancelCheckout: (checkoutId) => run("dps_checkout_cancel", { checkoutId }),
+        getOrder: (orderId) => run("dps_orders_get", { orderId }),
+        listOrders: (input) => run("dps_orders_list", input),
+        verifyPayment: (reference) => run("dps_payments_verify", { reference }),
+        checkSubscription: (input) => run("dps_subscriptions_check", input),
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Tenant-bound helpers (donation / subscription / invoice / product)
+// ────────────────────────────────────────────────────────────────────────────
+export { withTenant, } from "./tenant";

package/dist/tenant.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tenant-bound, domain-specific checkout helpers.
+ *
+ * These wrap the generic `DpsClient.createCheckout()` with strongly-typed
+ * helpers for each checkout type we support across the Duabalabs ecosystem
+ * (donations, subscriptions, invoices, …). New checkout types are added
+ * here so every consuming app benefits without re-implementing payload
+ * boilerplate.
+ *
+ * Usage (browser):
+ *
+ *   const tenant = withTenant(createDpsClient({ Parse }), {
+ *     appId: "duabanti",
+ *     storeId: "duabanti",
+ *     referencePrefix: "DNTI",
+ *   });
+ *   await tenant.createDonation({ amount: 50, customer: { email } });
+ *
+ * Usage (server):
+ *
+ *   const tenant = withTenant(createDpsServerClient({ ... }), {
+ *     appId: "duabaconnect",
+ *     storeId: "duabaconnect",
+ *   });
+ *   await tenant.startSubscription({ tier: "starter", planCode, … });
+ */
+import type { DpsClient, CheckoutSession, CheckoutCustomer, CheckoutLineItem, CheckoutFlow, PaymentVerification, SubscriptionStatus, PaystackSplitConfig } from "./index";
+export interface TenantConfig {
+    /** Opaque tenant tag — e.g. `duabanti`, `duabaconnect`, `duabatrade`. */
+    appId: string;
+    /** Sellub `storeId` for this tenant (or a tenant-specific id when not on sellub). */
+    storeId: string;
+    /** Optional: when set, vendure-flow checkouts can be created. */
+    channelToken?: string;
+    /** Optional default reference prefix passed to dps-server. */
+    referencePrefix?: string;
+    /** Optional default currency (ISO 4217) — defaults to `GHS`. */
+    defaultCurrency?: string;
+    /** Optional default Paystack split config applied when caller doesn't override. */
+    defaultSplitConfig?: PaystackSplitConfig;
+}
+export interface DonationCheckoutInput {
+    amount: number;
+    currency?: string;
+    customer: CheckoutCustomer;
+    campaign?: string;
+    callbackUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SubscriptionCheckoutInput {
+    /** Free-form tier id e.g. `starter`, `growth`, `pro`. */
+    tier: string;
+    /** Paystack subscription plan code (server creates the subscription against this). */
+    planCode: string;
+    /** First charge amount in major units. */
+    amount: number;
+    currency?: string;
+    customer: CheckoutCustomer;
+    callbackUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface InvoiceCheckoutInput {
+    /** Human-facing invoice / quote reference. Stored in `metadata.reference`. */
+    reference: string;
+    amount: number;
+    currency?: string;
+    customer: CheckoutCustomer;
+    description?: string;
+    /** Optional explicit line items (otherwise a single line is synthesized for vendure flow). */
+    lineItems?: CheckoutLineItem[];
+    /** Force a flow. Defaults to `vendure` when `channelToken` is set, else `direct`. */
+    flow?: CheckoutFlow;
+    callbackUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ProductCheckoutInput {
+    lineItems: CheckoutLineItem[];
+    customer: CheckoutCustomer;
+    currency?: string;
+    /** Optional override; defaults to summing `lineItems`. */
+    amount?: number;
+    callbackUrl?: string;
+    metadata?: Record<string, unknown>;
+    splitConfig?: PaystackSplitConfig;
+}
+export interface TenantClient {
+    /** Underlying generic DPS client — escape hatch for advanced calls. */
+    readonly client: DpsClient;
+    readonly config: Readonly<TenantConfig>;
+    /** Charge a one-off donation through the `direct` flow. */
+    createDonation(input: DonationCheckoutInput): Promise<CheckoutSession>;
+    /** Start a Paystack-backed recurring subscription via the `direct` flow + plan code. */
+    startSubscription(input: SubscriptionCheckoutInput): Promise<CheckoutSession>;
+    /** Pay an invoice / quote (vendure when channelToken is configured, else direct). */
+    createInvoice(input: InvoiceCheckoutInput): Promise<CheckoutSession>;
+    /** Catalog product checkout — requires line items + a configured channel for vendure. */
+    createProductCheckout(input: ProductCheckoutInput): Promise<CheckoutSession>;
+    /** Verify a Paystack reference (use on thank-you / callback pages). */
+    verifyPayment(reference: string): Promise<PaymentVerification>;
+    /** Check whether a customer email has an active subscription with this tenant. */
+    hasActiveSubscription(input: {
+        email: string;
+    }): Promise<SubscriptionStatus>;
+}
+export declare function withTenant(client: DpsClient, config: TenantConfig): TenantClient;

package/dist/tenant.js

@@ -0,0 +1,151 @@
+/**
+ * Tenant-bound, domain-specific checkout helpers.
+ *
+ * These wrap the generic `DpsClient.createCheckout()` with strongly-typed
+ * helpers for each checkout type we support across the Duabalabs ecosystem
+ * (donations, subscriptions, invoices, …). New checkout types are added
+ * here so every consuming app benefits without re-implementing payload
+ * boilerplate.
+ *
+ * Usage (browser):
+ *
+ *   const tenant = withTenant(createDpsClient({ Parse }), {
+ *     appId: "duabanti",
+ *     storeId: "duabanti",
+ *     referencePrefix: "DNTI",
+ *   });
+ *   await tenant.createDonation({ amount: 50, customer: { email } });
+ *
+ * Usage (server):
+ *
+ *   const tenant = withTenant(createDpsServerClient({ ... }), {
+ *     appId: "duabaconnect",
+ *     storeId: "duabaconnect",
+ *   });
+ *   await tenant.startSubscription({ tier: "starter", planCode, … });
+ */
+// ────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ────────────────────────────────────────────────────────────────────────────
+function defaultCurrency(cfg, override) {
+    return override || cfg.defaultCurrency || "GHS";
+}
+function baseFields(cfg) {
+    return {
+        appId: cfg.appId,
+        storeId: cfg.storeId,
+        referencePrefix: cfg.referencePrefix,
+    };
+}
+export function withTenant(client, config) {
+    if (!config.appId)
+        throw new Error("withTenant: `appId` is required");
+    if (!config.storeId)
+        throw new Error("withTenant: `storeId` is required");
+    const cfg = { ...config };
+    return {
+        client,
+        config: cfg,
+        createDonation(input) {
+            const payload = {
+                ...baseFields(cfg),
+                flow: "direct",
+                currency: defaultCurrency(cfg, input.currency),
+                amount: input.amount,
+                customer: input.customer,
+                callbackUrl: input.callbackUrl,
+                splitConfig: cfg.defaultSplitConfig,
+                metadata: {
+                    type: "donation",
+                    campaign: input.campaign,
+                    source: cfg.appId,
+                    ...input.metadata,
+                },
+            };
+            return client.createCheckout(payload);
+        },
+        startSubscription(input) {
+            if (!input.planCode) {
+                throw new Error(`startSubscription: planCode is required (no Paystack plan configured for tier "${input.tier}").`);
+            }
+            const payload = {
+                ...baseFields(cfg),
+                flow: "direct",
+                currency: defaultCurrency(cfg, input.currency),
+                amount: input.amount,
+                customer: input.customer,
+                paystackPlanCode: input.planCode,
+                callbackUrl: input.callbackUrl,
+                splitConfig: cfg.defaultSplitConfig,
+                metadata: {
+                    type: "subscription",
+                    tier: input.tier,
+                    source: cfg.appId,
+                    ...input.metadata,
+                },
+            };
+            return client.createCheckout(payload);
+        },
+        createInvoice(input) {
+            const flow = input.flow || (cfg.channelToken ? "vendure" : "direct");
+            const lineItems = input.lineItems ||
+                (flow === "vendure"
+                    ? [
+                        {
+                            name: input.description || `Invoice ${input.reference}`,
+                            quantity: 1,
+                            unitPrice: input.amount,
+                        },
+                    ]
+                    : undefined);
+            const payload = {
+                ...baseFields(cfg),
+                flow,
+                channelToken: flow === "vendure" ? cfg.channelToken : undefined,
+                currency: defaultCurrency(cfg, input.currency),
+                amount: input.amount,
+                lineItems,
+                customer: input.customer,
+                callbackUrl: input.callbackUrl,
+                splitConfig: cfg.defaultSplitConfig,
+                metadata: {
+                    type: "invoice",
+                    reference: input.reference,
+                    description: input.description,
+                    source: cfg.appId,
+                    ...input.metadata,
+                },
+            };
+            return client.createCheckout(payload);
+        },
+        createProductCheckout(input) {
+            const flow = cfg.channelToken ? "vendure" : "direct";
+            if (flow === "vendure" && !cfg.channelToken) {
+                throw new Error("createProductCheckout: vendure flow requires channelToken on TenantConfig.");
+            }
+            const payload = {
+                ...baseFields(cfg),
+                flow,
+                channelToken: cfg.channelToken,
+                currency: defaultCurrency(cfg, input.currency),
+                amount: input.amount,
+                lineItems: input.lineItems,
+                customer: input.customer,
+                callbackUrl: input.callbackUrl,
+                splitConfig: input.splitConfig || cfg.defaultSplitConfig,
+                metadata: {
+                    type: "product",
+                    source: cfg.appId,
+                    ...input.metadata,
+                },
+            };
+            return client.createCheckout(payload);
+        },
+        verifyPayment(reference) {
+            return client.verifyPayment(reference);
+        },
+        hasActiveSubscription(input) {
+            return client.checkSubscription({ appId: cfg.appId, email: input.email });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@duabalabs/dps-client",
+  "version": "0.1.0",
+  "description": "Typed client for the DPS unified checkout/commerce orchestration cloud functions.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "parse": ">=4 <6"
+  },
+  "devDependencies": {
+    "parse": "^5.3.0",
+    "typescript": "^5.4.0"
+  }
+}