@optizio/merchant-identity 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared merchant-identity contract for the merchant-hub portfolio.
+ *
+ * Consumed by:
+ *  - the `merchant-identity` service Worker, which implements `IdentityClient`
+ *    against the shared D1, and
+ *  - portfolio apps (DiscountKit, CodeBulk, Stackable), which call the service
+ *    over an RPC service binding through the `identity()` seam below.
+ *
+ * This package holds only types + pure helpers, so it has no Cloudflare or
+ * runtime dependencies and is safe to import anywhere.
+ */
+export interface MerchantRecord {
+    shopDomain: string;
+    shopGid?: string | null;
+    name?: string | null;
+    email?: string | null;
+    planName?: string | null;
+    shopifyPlus?: boolean | null;
+    partnerDevelopment?: boolean | null;
+    currencyCode?: string | null;
+    ianaTimezone?: string | null;
+    primaryLocale?: string | null;
+    subscribedPlan?: string | null;
+    installedAt?: string | null;
+    createdAt?: string | null;
+    lastIdentifiedAt?: string | null;
+}
+export interface MerchantAppRecord {
+    shopDomain: string;
+    appId: string;
+    appHandle?: string | null;
+    installedAt?: string | null;
+    uninstalledAt?: string | null;
+    firstSeenAt?: string | null;
+    lastSeenAt?: string | null;
+}
+export interface MerchantUserRecord {
+    shopDomain: string;
+    userId: string;
+    firstName?: string | null;
+    lastName?: string | null;
+    email?: string | null;
+    emailVerified?: boolean | null;
+    accountOwner?: boolean | null;
+    locale?: string | null;
+    firstSeenAt?: string | null;
+    lastSeenAt?: string | null;
+}
+export interface MerchantSubscriptionRecord {
+    shopDomain: string;
+    appId?: string;
+    topic?: string;
+    userId?: string;
+    subscribed: boolean;
+    source?: string | null;
+}
+export interface StoredMerchant {
+    shopDomain: string;
+    shopGid: string | null;
+    name: string | null;
+    email: string | null;
+    planName: string | null;
+    shopifyPlus: boolean | null;
+    partnerDevelopment: boolean | null;
+    currencyCode: string | null;
+    ianaTimezone: string | null;
+    primaryLocale: string | null;
+    subscribedPlan: string | null;
+    installedAt: string | null;
+    lastIdentifiedAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface StoredMerchantUser {
+    shopDomain: string;
+    userId: string;
+    firstName: string | null;
+    lastName: string | null;
+    email: string | null;
+    emailVerified: boolean | null;
+    accountOwner: boolean | null;
+    locale: string | null;
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+}
+export interface StoredMerchantApp {
+    shopDomain: string;
+    appId: string;
+    appHandle: string | null;
+    installedAt: string | null;
+    uninstalledAt: string | null;
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+}
+export interface StoredMerchantSubscription {
+    shopDomain: string;
+    appId: string;
+    topic: string;
+    userId: string;
+    subscribed: boolean;
+    source: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface StoreDetails {
+    merchant: StoredMerchant | null;
+    users: StoredMerchantUser[];
+    apps: StoredMerchantApp[];
+    subscriptions: StoredMerchantSubscription[];
+}
+/** Sentinel stored for the `app_id` / `user_id` columns when a row applies to
+ * every app / every user of a store. */
+export declare const SUBSCRIPTION_ALL_SCOPES = "*";
+/** Sentinel stored for the `topic` column when a row applies to all topics. */
+export declare const SUBSCRIPTION_ALL_TOPICS = "all";
+export interface SubscriptionScope {
+    appId?: string;
+    topic?: string;
+    userId?: string;
+    /** Fallback returned by `isSubscribed` when no row matches (opt-out default). */
+    default?: boolean;
+}
+/**
+ * Resolve the effective subscribed state for a scope from a store's rows.
+ * Most-specific match wins (user > app > topic); returns `null` when nothing
+ * matches so callers can apply their own default.
+ */
+export declare function resolveSubscription(rows: StoredMerchantSubscription[], scope?: SubscriptionScope): boolean | null;
+/**
+ * The method surface exposed by the `merchant-identity` service Worker and
+ * consumed by apps over an RPC service binding (`env.IDENTITY`). All arguments
+ * and return values are structured-cloneable so they cross the RPC boundary.
+ */
+export interface IdentityClient {
+    captureMerchant(input: MerchantRecord): Promise<void>;
+    captureMerchantUser(input: MerchantUserRecord): Promise<void>;
+    touchMerchantApp(input: MerchantAppRecord): Promise<void>;
+    markAppUninstalled(shopDomain: string, appId: string): Promise<void>;
+    setSubscription(input: MerchantSubscriptionRecord): Promise<void>;
+    isSubscribed(shopDomain: string, scope?: SubscriptionScope): Promise<boolean>;
+    getStoreDetails(shopDomain: string): Promise<StoreDetails>;
+}
+/**
+ * No-op client used when the service is unavailable (local dev) or explicitly
+ * disabled via `IDENTITY_DISABLED`. Reads return empty/opt-out defaults so the
+ * host app behaves identically minus the capture side effects.
+ */
+export declare const NOOP_IDENTITY: IdentityClient;
+/**
+ * Single seam every app uses instead of touching `env.IDENTITY` directly.
+ * Returns the real binding when present and enabled, otherwise a no-op client
+ * so apps spin up and run without the service (local dev). This is the point at
+ * which a future local direct-D1 fallback could be swapped in without changing
+ * any call sites.
+ */
+export declare function identity(binding: IdentityClient | null | undefined, disabled?: boolean | string): IdentityClient;

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * Shared merchant-identity contract for the merchant-hub portfolio.
+ *
+ * Consumed by:
+ *  - the `merchant-identity` service Worker, which implements `IdentityClient`
+ *    against the shared D1, and
+ *  - portfolio apps (DiscountKit, CodeBulk, Stackable), which call the service
+ *    over an RPC service binding through the `identity()` seam below.
+ *
+ * This package holds only types + pure helpers, so it has no Cloudflare or
+ * runtime dependencies and is safe to import anywhere.
+ */
+/* -------------------------------------------------------------------------- */
+/* Subscriptions                                                              */
+/* -------------------------------------------------------------------------- */
+/** Sentinel stored for the `app_id` / `user_id` columns when a row applies to
+ * every app / every user of a store. */
+export const SUBSCRIPTION_ALL_SCOPES = '*';
+/** Sentinel stored for the `topic` column when a row applies to all topics. */
+export const SUBSCRIPTION_ALL_TOPICS = 'all';
+/**
+ * Resolve the effective subscribed state for a scope from a store's rows.
+ * Most-specific match wins (user > app > topic); returns `null` when nothing
+ * matches so callers can apply their own default.
+ */
+export function resolveSubscription(rows, scope = {}) {
+    const appId = scope.appId ?? SUBSCRIPTION_ALL_SCOPES;
+    const topic = scope.topic ?? SUBSCRIPTION_ALL_TOPICS;
+    const userId = scope.userId ?? SUBSCRIPTION_ALL_SCOPES;
+    let best = null;
+    for (const row of rows) {
+        const appScore = row.appId === appId ? 2 : row.appId === SUBSCRIPTION_ALL_SCOPES ? 0 : -1;
+        const topicScore = row.topic === topic ? 1 : row.topic === SUBSCRIPTION_ALL_TOPICS ? 0 : -1;
+        const userScore = row.userId === userId ? 4 : row.userId === SUBSCRIPTION_ALL_SCOPES ? 0 : -1;
+        if (appScore < 0 || topicScore < 0 || userScore < 0)
+            continue;
+        const score = appScore + topicScore + userScore;
+        if (!best || score > best.score)
+            best = { score, subscribed: row.subscribed };
+    }
+    return best ? best.subscribed : null;
+}
+/**
+ * No-op client used when the service is unavailable (local dev) or explicitly
+ * disabled via `IDENTITY_DISABLED`. Reads return empty/opt-out defaults so the
+ * host app behaves identically minus the capture side effects.
+ */
+export const NOOP_IDENTITY = {
+    async captureMerchant() { },
+    async captureMerchantUser() { },
+    async touchMerchantApp() { },
+    async markAppUninstalled() { },
+    async setSubscription() { },
+    async isSubscribed() {
+        return true;
+    },
+    async getStoreDetails() {
+        return { merchant: null, users: [], apps: [], subscriptions: [] };
+    },
+};
+/**
+ * Single seam every app uses instead of touching `env.IDENTITY` directly.
+ * Returns the real binding when present and enabled, otherwise a no-op client
+ * so apps spin up and run without the service (local dev). This is the point at
+ * which a future local direct-D1 fallback could be swapped in without changing
+ * any call sites.
+ */
+export function identity(binding, disabled) {
+    if (!binding || disabled === true || disabled === 'true') {
+        return NOOP_IDENTITY;
+    }
+    return binding;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@optizio/merchant-identity",
+  "version": "0.1.0",
+  "description": "Shared merchant/user identity types + RPC client contract for the merchant-hub portfolio.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  }
+}