@basezero/sdk 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @basezero/sdk
+
+Small, dependency-free **server-side** client for BaseZero app events. Requires an existing Shopify-mapped BaseZero Project and its API key. No install-state tracking in the app, no Shopify token sharing, no email automation.
+
+```ts
+import { BaseZero } from '@basezero/sdk';
+
+const basezero = new BaseZero({
+  baseUrl: 'https://YOUR_BASEZERO_HOST',
+  apiKey: process.env.BASEZERO_API_KEY!,
+});
+
+// After authenticating a live shop request:
+await basezero.identify({
+  platformId: String(shop.id),
+  myshopifyDomain: shop.myshopifyDomain,
+  name: shop.name,
+  email: shop.email,
+});
+
+// Only after authenticating an app/uninstalled webhook:
+await basezero.uninstall(
+  { platformId: String(payload.id) },
+  {
+    eventId: `shopify-uninstall:${shopifyEventId}`,
+    occurredAt: new Date(shopifyTriggeredAt).toISOString(),
+  },
+);
+```
+
+Use Shopify's original `X-Shopify-Event-Id` (fallback `X-Shopify-Webhook-Id`) and `X-Shopify-Triggered-At` for uninstalls. Missing metadata must be recovered, not replaced with the retry time.
+
+BaseZero derives an inferred install from the first identify, suppresses repeated identify lifecycle events, and derives an inferred reinstall after an uninstall. First identify is not proof of the original Shopify install date. Missed uninstall cycles cannot be inferred from identify alone. Don't identify shops by scanning stale stored sessions.
+
+## Delivery
+
+Every call is awaited. Defaults: 3 attempts, 5-second request timeout, exponential retry delay. Network failures, 408, 429 and 5xx retry with identical event ID, time and content. Configure `attempts` (1–5), `timeoutMs` (1–30000), or a custom `fetch`. HTTPS is mandatory except localhost. Redirects and browser usage are rejected.
+
+The retry budget may exceed Shopify's webhook acknowledgement deadline: prefer a durable webhook queue. Never acknowledge an uninstall successfully after swallowing an SDK error.
+
+Retries are **not durable across process death**. To use your existing job/queue system:
+
+```ts
+import { createIdentifyEvent, createUninstallEvent } from '@basezero/sdk';
+
+const event = createIdentifyEvent(customer);
+// Persist the envelope once; retry the same saved object after failures/restarts.
+await basezero.send(event);
+
+const removal = createUninstallEvent({ platformId: '123' }, {
+  eventId: 'shopify-uninstall:original-event-id',
+  occurredAt: '2026-01-01T00:00:00.000Z',
+});
+await basezero.send(removal);
+```
+
+`BaseZeroError` exposes `code`, `status`, and the original `event` for recovery. The event contains customer data; don't log the whole error. Reusing an ID with different contents is a 409 conflict. Never regenerate an occurrence time for a retry.
+
+`platformId` is a numeric string or Shopify/Partner Shop GID. Profiles accept `myshopifyDomain`, optional `name`, and optional `email`; no access token or arbitrary metadata. The raw envelope is `{ eventId, occurredAt, type, customer }`. Successful writes return `{ eventId, customerId, installationId }` after durable persistence.
+
+## Install
+
+```bash
+npm install @basezero/sdk
+# or
+pnpm add @basezero/sdk
+```
+
+## Build/install from this repository
+
+For local development, from the BaseZero repository:
+
+```bash
+npm pack ./packages/sdk --pack-destination /tmp
+```
+
+Then in the app repository:
+
+```bash
+npm install /tmp/basezero-sdk-0.1.0.tgz
+```
+
+Provisioning, API reads, storage semantics and limitations: `docs/app-events.md` in the BaseZero repository.

package/dist/contracts.d.ts

@@ -0,0 +1,42 @@
+export type IdentifyInput = {
+    platformId: string;
+    myshopifyDomain: string;
+    name?: string;
+    email?: string;
+};
+export type UninstallInput = {
+    platformId: string;
+};
+export type EventDelivery = {
+    eventId: string;
+    occurredAt: string;
+};
+export type AppEvent = EventDelivery & ({
+    type: "identify";
+    customer: IdentifyInput;
+} | {
+    type: "uninstall";
+    customer: UninstallInput;
+});
+export type EventReceipt = {
+    eventId: string;
+    customerId: string;
+    installationId: string;
+};
+export type AppCustomer = {
+    customerId: string;
+    installationId: string;
+    firstSeenAt: string;
+    status: "installed" | "uninstalled";
+    lastObservedAt: string;
+    events: Array<{
+        eventId: string;
+        platformEventId: string;
+        rawAppEventId: string;
+        netChange: null;
+        ignored: number;
+        type: "installed" | "reinstalled" | "uninstalled";
+        occurredAt: string;
+        quality: "inferred" | "confirmed";
+    }>;
+};

package/dist/contracts.js

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

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { AppEvent, EventDelivery, EventReceipt, IdentifyInput, UninstallInput } from "./contracts.js";
+export type { AppCustomer, AppEvent, EventDelivery, EventReceipt, IdentifyInput, UninstallInput, } from "./contracts.js";
+export type BaseZeroOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetch?: typeof fetch;
+    attempts?: number;
+    timeoutMs?: number;
+};
+export declare class BaseZeroError extends Error {
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly event: AppEvent;
+    constructor(input: {
+        code: string;
+        event: AppEvent;
+        status?: number;
+    });
+}
+export declare function createIdentifyEvent(customer: IdentifyInput, delivery?: Partial<EventDelivery>): AppEvent;
+export declare function createUninstallEvent(customer: UninstallInput, delivery: EventDelivery): AppEvent;
+export declare class BaseZero {
+    #private;
+    constructor(options: BaseZeroOptions);
+    identify(customer: IdentifyInput, delivery?: Partial<EventDelivery>): Promise<EventReceipt>;
+    uninstall(customer: UninstallInput, delivery: EventDelivery): Promise<EventReceipt>;
+    send(event: AppEvent): Promise<EventReceipt>;
+}

package/dist/index.js

@@ -0,0 +1,142 @@
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const RETRY_DELAY_MS = 250;
+export class BaseZeroError extends Error {
+    code;
+    status;
+    event;
+    constructor(input) {
+        super(`BaseZero: ${input.code}`);
+        this.name = "BaseZeroError";
+        this.code = input.code;
+        this.status = input.status;
+        this.event = input.event;
+    }
+}
+export function createIdentifyEvent(customer, delivery = {}) {
+    return {
+        eventId: delivery.eventId ?? crypto.randomUUID(),
+        occurredAt: delivery.occurredAt ?? new Date().toISOString(),
+        type: "identify",
+        customer: { ...customer },
+    };
+}
+export function createUninstallEvent(customer, delivery) {
+    return {
+        eventId: delivery.eventId,
+        occurredAt: delivery.occurredAt,
+        type: "uninstall",
+        customer: { ...customer },
+    };
+}
+export class BaseZero {
+    #url;
+    #apiKey;
+    #fetch;
+    #attempts;
+    #timeoutMs;
+    constructor(options) {
+        if (typeof window !== "undefined")
+            throw new Error("BaseZero SDK is server-only");
+        const url = new URL(options.baseUrl);
+        const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== "/")
+            throw new Error("baseUrl must be an HTTPS origin (HTTP allowed on localhost)");
+        if (!/^bz_[a-f0-9]{64}$/.test(options.apiKey))
+            throw new Error("Invalid BaseZero API key");
+        this.#url = new URL("/api/app/v1/events", url).href;
+        this.#apiKey = options.apiKey;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isInteger(this.#attempts) ||
+            this.#attempts < 1 ||
+            this.#attempts > 5)
+            throw new Error("attempts must be between 1 and 5");
+        if (!Number.isFinite(this.#timeoutMs) ||
+            this.#timeoutMs <= 0 ||
+            this.#timeoutMs > 30_000)
+            throw new Error("timeoutMs must be between 1 and 30000");
+    }
+    identify(customer, delivery) {
+        return this.send(createIdentifyEvent(customer, delivery));
+    }
+    uninstall(customer, delivery) {
+        return this.send(createUninstallEvent(customer, delivery));
+    }
+    async send(event) {
+        const snapshot = structuredClone(event);
+        const body = JSON.stringify(snapshot);
+        for (let attempt = 0; attempt < this.#attempts; attempt++) {
+            try {
+                return await this.#attempt({ event: snapshot, body });
+            }
+            catch (error) {
+                if (!(error instanceof BaseZeroError))
+                    throw error;
+                const retryable = error.status === undefined ||
+                    error.status === 408 ||
+                    error.status === 429 ||
+                    error.status >= 500;
+                if (!retryable || attempt === this.#attempts - 1)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS * 2 ** attempt));
+            }
+        }
+        throw new BaseZeroError({ code: "delivery_failed", event: snapshot });
+    }
+    async #attempt(input) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.#timeoutMs);
+        try {
+            const response = await this.#fetch(this.#url, {
+                method: "POST",
+                redirect: "error",
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${this.#apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: input.body,
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new BaseZeroError({
+                    code: `http_${response.status}`,
+                    status: response.status,
+                    event: input.event,
+                });
+            }
+            const receipt = await response.json();
+            if (!isReceipt(receipt) || receipt.eventId !== input.event.eventId)
+                throw new BaseZeroError({
+                    code: "invalid_response",
+                    event: input.event,
+                });
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof BaseZeroError)
+                throw error;
+            throw new BaseZeroError({ code: "network_error", event: input.event });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+function isReceipt(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "eventId" in value &&
+        typeof value.eventId === "string" &&
+        "customerId" in value &&
+        typeof value.customerId === "string" &&
+        "installationId" in value &&
+        typeof value.installationId === "string");
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@basezero/sdk",
+  "version": "0.1.0",
+  "description": "Server-side identify and uninstall events for BaseZero",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": { "build": "tsc -p tsconfig.json", "prepack": "npm run build" },
+  "engines": { "node": ">=20" }
+}