@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.

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:

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

npm install @basezero/sdk
# or
pnpm add @basezero/sdk

Build/install from this repository

For local development, from the BaseZero repository:

npm pack ./packages/sdk --pack-destination /tmp

Then in the app repository:

npm install /tmp/basezero-sdk-0.1.0.tgz

Provisioning, API reads, storage semantics and limitations: docs/app-events.md in the BaseZero repository.