@occassionly/partner-sdk 0.1.0-ftpartner.4

package/README.md

@@ -0,0 +1,238 @@
+# @occassionly/partner-sdk
+
+Official SDK for the Occassionly Partner API.
+
+## Install
+
+```bash
+npm i @occassionly/partner-sdk
+```
+
+For builds published automatically from branch `ft/partner`:
+
+```bash
+npm i @occassionly/partner-sdk@ft-partner
+```
+
+## Usage
+
+```ts
+import { createClient } from "@occassionly/partner-sdk";
+
+const client = createClient({
+  baseUrl: "https://api.occassionly.com/api",
+  partnerId: process.env.OCC_PARTNER_ID!,
+  apiKeyId: process.env.OCC_API_KEY_ID!,
+  apiSecret: process.env.OCC_API_SECRET!,
+});
+
+const credits = await client.getCredits();
+```
+
+## Methods
+
+- `getCredits()`
+- `createEvent(payload)`
+- `issueCard(payload)`
+- `issueCardsBulk(payload)`
+- `revokeCard(occCardId, payload?)`
+- `verify(payload)`
+- `listWebhookOutbox(params?)`
+- `retryDueWebhooks()`
+- `replayWebhook(webhookEventId)`
+
+## Payloads and sample responses
+
+### `getCredits()`
+
+Response:
+
+```json
+{
+  "partner_id": "partner_demo",
+  "credits_total": 500,
+  "credits_used": 120,
+  "credits_remaining": 380
+}
+```
+
+### `createEvent(payload)`
+
+Payload:
+
+```json
+{
+  "partner_event_id": "evt_12345",
+  "event_name": "Wedding Reception",
+  "start_at": "2026-03-28T13:00:00.000Z",
+  "end_at": "2026-03-28T18:00:00.000Z",
+  "timezone": "Africa/Lagos",
+  "template": { "theme": "classic" }
+}
+```
+
+Response:
+
+```json
+{
+  "occ_event_id": "67f0f7c2e7f8f92b4d0e0c11",
+  "status": "active"
+}
+```
+
+### `issueCard(payload)`
+
+Payload:
+
+```json
+{
+  "issue_ref": "evt_12345_guest_001",
+  "partner_event_id": "evt_12345",
+  "partner_guest_id": "guest_001",
+  "guest_name": "Ibrahim Musa",
+  "email": "ibrahim@example.com"
+}
+```
+
+Response:
+
+```json
+{
+  "occ_card_id": "occ_card_ab12cd34",
+  "status": "issued",
+  "card_url": "https://occassionly.com/c/occ_card_ab12cd34",
+  "qr_payload": "OCCP|occ_card_ab12cd34|ea73..."
+}
+```
+
+### `issueCardsBulk(payload)`
+
+Payload:
+
+```json
+{
+  "items": [
+    {
+      "issue_ref": "evt_12345_guest_001",
+      "partner_event_id": "evt_12345",
+      "partner_guest_id": "guest_001",
+      "guest_name": "Ibrahim Musa"
+    },
+    {
+      "issue_ref": "evt_12345_guest_002",
+      "partner_event_id": "evt_12345",
+      "partner_guest_id": "guest_002",
+      "guest_name": "Aisha Bello"
+    }
+  ]
+}
+```
+
+Response:
+
+```json
+{
+  "total": 2,
+  "created": 2,
+  "idempotent": 0,
+  "failed": 0,
+  "results": []
+}
+```
+
+### `verify(payload)`
+
+Payload:
+
+```json
+{
+  "qr_payload": "OCCP|occ_card_ab12cd34|ea73..."
+}
+```
+
+Response:
+
+```json
+{
+  "status": "valid",
+  "occ_card_id": "occ_card_ab12cd34"
+}
+```
+
+Other `status` values: `invalid`, `already_verified`, `revoked`.
+
+### `revokeCard(occCardId, payload?)`
+
+Payload:
+
+```json
+{
+  "reason": "manual_revoke"
+}
+```
+
+Response:
+
+```json
+{
+  "occ_card_id": "occ_card_ab12cd34",
+  "status": "revoked"
+}
+```
+
+### `listWebhookOutbox(params?)`
+
+Query params:
+- `status`: `pending | failed | dead_letter | delivered`
+- `event_type`: string
+- `limit`: number
+- `cursor`: string
+
+Response:
+
+```json
+{
+  "items": [
+    {
+      "webhook_event_id": "4f9a...",
+      "event_type": "card.issued",
+      "status": "delivered"
+    }
+  ],
+  "next_cursor": null
+}
+```
+
+### `retryDueWebhooks()`
+
+Response:
+
+```json
+{
+  "scanned": 10,
+  "retried": 3
+}
+```
+
+### `replayWebhook(webhookEventId)`
+
+Response:
+
+```json
+{
+  "replayed": true
+}
+```
+
+## Common error response
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INSUFFICIENT_CREDITS",
+    "message": "Partner credit balance exhausted.",
+    "details": null
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+type HttpMethod = "GET" | "POST";
+export type PartnerClientOptions = {
+    baseUrl: string;
+    partnerId: string;
+    apiKeyId: string;
+    apiSecret: string;
+    fetchImpl?: typeof fetch;
+};
+export declare class PartnerApiError extends Error {
+    status: number;
+    code?: string;
+    details?: unknown;
+    constructor(message: string, status: number, code?: string, details?: unknown);
+}
+export declare function createClient(options: PartnerClientOptions): {
+    request: <T>(method: HttpMethod, path: string, body?: unknown, query?: Record<string, string | number | boolean | undefined>) => Promise<T>;
+    getCredits: () => Promise<{
+        partner_id: string;
+        credits_total: number;
+        credits_used: number;
+        credits_remaining: number;
+    }>;
+    createEvent: (payload: {
+        partner_event_id: string;
+        event_name: string;
+        start_at?: string;
+        end_at?: string;
+        timezone?: string;
+        template?: Record<string, unknown>;
+    }) => Promise<{
+        occ_event_id: string;
+        status: string;
+    }>;
+    issueCard: (payload: {
+        issue_ref: string;
+        partner_event_id: string;
+        partner_guest_id: string;
+        guest_name: string;
+        email?: string;
+        phone?: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<{
+        occ_card_id: string;
+        status: string;
+        card_url: string;
+        qr_payload: string;
+    }>;
+    issueCardsBulk: (payload: {
+        items: Array<{
+            issue_ref: string;
+            partner_event_id: string;
+            partner_guest_id: string;
+            guest_name: string;
+            email?: string;
+            phone?: string;
+            metadata?: Record<string, unknown>;
+        }>;
+    }) => Promise<{
+        total: number;
+        created: number;
+        idempotent: number;
+        failed: number;
+        results: Array<Record<string, unknown>>;
+    }>;
+    revokeCard: (occCardId: string, payload?: {
+        reason?: string;
+    }) => Promise<{
+        occ_card_id: string;
+        status: string;
+    }>;
+    verify: (payload: {
+        qr_payload: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<{
+        status: "valid" | "invalid" | "already_verified" | "revoked";
+        occ_card_id?: string;
+    }>;
+    listWebhookOutbox: (params?: {
+        status?: "pending" | "failed" | "dead_letter" | "delivered";
+        event_type?: string;
+        limit?: number;
+        cursor?: string;
+    }) => Promise<{
+        items: Array<Record<string, unknown>>;
+        next_cursor: string | null;
+    }>;
+    retryDueWebhooks: () => Promise<{
+        scanned: number;
+        retried: number;
+    }>;
+    replayWebhook: (webhookEventId: string) => Promise<{
+        replayed: boolean;
+    }>;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,89 @@
+import { createHmac } from "crypto";
+export class PartnerApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, status, code, details) {
+        super(message);
+        this.name = "PartnerApiError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+const normalizeBaseUrl = (baseUrl) => baseUrl.replace(/\/+$/, "");
+const normalizePath = (path) => {
+    const trimmed = path.trim();
+    if (!trimmed)
+        throw new Error("Path cannot be empty");
+    if (trimmed.startsWith("/api/v1/partner/"))
+        return trimmed;
+    if (trimmed.startsWith("/v1/partner/"))
+        return `/api${trimmed}`;
+    if (trimmed.startsWith("/"))
+        return `/api${trimmed}`;
+    return `/api/${trimmed}`;
+};
+const stableStringify = (value) => {
+    if (value == null)
+        return "";
+    return JSON.stringify(value);
+};
+const sign = (secret, canonical) => createHmac("sha256", secret).update(canonical, "utf8").digest("hex");
+const buildHeaders = (input) => ({
+    "Content-Type": "application/json",
+    "x-partner-id": input.partnerId,
+    "x-api-key": input.apiKeyId,
+    "x-timestamp": input.timestamp,
+    "x-signature": input.signature,
+});
+async function handleResponse(res) {
+    const payload = (await res.json().catch(() => ({})));
+    if (!res.ok || !payload || payload.success === false) {
+        const failure = payload;
+        throw new PartnerApiError(failure?.error?.message || `Partner API request failed (${res.status})`, res.status, failure?.error?.code, failure?.error?.details);
+    }
+    return payload.data;
+}
+export function createClient(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const request = async (method, path, body, query) => {
+        const canonicalPath = normalizePath(path);
+        const bodyText = method === "POST" ? stableStringify(body) : "";
+        const timestamp = Date.now().toString();
+        const canonical = `${timestamp}${method}${canonicalPath}${bodyText}`;
+        const signature = sign(options.apiSecret, canonical);
+        const url = new URL(`${baseUrl}${canonicalPath}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const res = await fetchImpl(url.toString(), {
+            method,
+            headers: buildHeaders({
+                partnerId: options.partnerId,
+                apiKeyId: options.apiKeyId,
+                signature,
+                timestamp,
+            }),
+            body: method === "POST" ? bodyText : undefined,
+        });
+        return handleResponse(res);
+    };
+    return {
+        request,
+        getCredits: () => request("GET", "/v1/partner/credits"),
+        createEvent: (payload) => request("POST", "/v1/partner/events", payload),
+        issueCard: (payload) => request("POST", "/v1/partner/cards", payload),
+        issueCardsBulk: (payload) => request("POST", "/v1/partner/cards/bulk", payload),
+        revokeCard: (occCardId, payload) => request("POST", `/v1/partner/cards/${encodeURIComponent(occCardId)}/revoke`, payload || {}),
+        verify: (payload) => request("POST", "/v1/partner/verify", payload),
+        listWebhookOutbox: (params) => request("GET", "/v1/partner/webhooks/outbox", undefined, params),
+        retryDueWebhooks: () => request("POST", "/v1/partner/webhooks/outbox/retry-due", {}),
+        replayWebhook: (webhookEventId) => request("POST", `/v1/partner/webhooks/outbox/${encodeURIComponent(webhookEventId)}/replay`, {}),
+    };
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@occassionly/partner-sdk",
+  "version": "0.1.0-ftpartner.4",
+  "description": "Official Occassionly Partner API SDK",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.33",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}