@munchi_oy/license-sdk 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @munchi_oy/license-sdk
+
+Asks the Munchi license service what a venue may use. Zero dependencies, Node 20+, ESM and CommonJS.
+
+```ts
+import { LicenseClient } from "@munchi_oy/license-sdk";
+
+const license = new LicenseClient({
+  baseUrl: process.env.LICENSE_URL, // one-license-api-{dev,prod} URL
+  serviceKey: process.env.LICENSE_KEY, // your service's key from Secret Manager
+  mode: "report", // start here: never blocks, calls onDenied instead
+  onDenied: (e) => logger.warn(e, "license would deny"),
+  onError: (e) => logger.error(e, "license service unreachable"),
+});
+
+if (await license.can(venueId, "kiosk")) { /* … */ }
+const kiosks = await license.limit(venueId, "kiosks"); // number, null = unlimited
+const snapshot = await license.entitlements(venueId); // full snapshot, null = unknown venue
+```
+
+| Behaviour | Default |
+|---|---|
+| Cache per venue, then revalidate with ETag (usually a 304) | `cacheTtlMs` 60 s, and always when the snapshot's `validUntil` passes |
+| Service unreachable | keeps the last snapshot for `maxStaleMs` (24 h); with nothing cached, `can()` allows |
+| Request timeout / retries | `timeoutMs` 2 s, one retry on network errors and 5xx |
+| Concurrent calls for one venue | share one request |
+| `mode: "enforce"` | `can()` returns `false` for features the venue doesn't have |
+
+Call `invalidate(venueId)` when you receive a `license.changed` event.

package/dist/index.cjs

@@ -0,0 +1,145 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LicenseClient: () => LicenseClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/license-client.ts
+var UNREACHABLE = /* @__PURE__ */ Symbol("unreachable");
+var LicenseClient = class {
+  static {
+    __name(this, "LicenseClient");
+  }
+  cache = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  options;
+  constructor(options) {
+    this.options = {
+      cacheTtlMs: 6e4,
+      maxStaleMs: 24 * 60 * 6e4,
+      timeoutMs: 2e3,
+      mode: "enforce",
+      fetch: globalThis.fetch,
+      ...options,
+      baseUrl: options.baseUrl.replace(/\/+$/, "")
+    };
+  }
+  /**
+  * The venue's snapshot, or `null` if the license service doesn't know the venue.
+  * `undefined` means the service couldn't be reached and nothing usable is cached.
+  */
+  async entitlements(venueId) {
+    const cached = this.cache.get(venueId);
+    if (cached && this.isFresh(cached)) return cached.snapshot;
+    const refreshed = await this.refresh(venueId, cached);
+    if (refreshed !== UNREACHABLE) return refreshed.snapshot;
+    if (cached && Date.now() - cached.checkedAt < this.options.maxStaleMs) return cached.snapshot;
+    return void 0;
+  }
+  /** Never blocks a venue because the license service is down: unknown state allows. */
+  async can(venueId, feature) {
+    const snapshot = await this.entitlements(venueId);
+    if (snapshot === void 0) return true;
+    const allowed = snapshot?.features.includes(feature) ?? false;
+    if (allowed) return true;
+    this.options.onDenied?.({
+      venueId,
+      feature,
+      reason: snapshot === null ? "unknown_venue" : "not_licensed"
+    });
+    return this.options.mode === "report";
+  }
+  /** `null` = unlimited, `undefined` = no such limit or no snapshot. */
+  async limit(venueId, key) {
+    return (await this.entitlements(venueId))?.limits[key];
+  }
+  /** Drop the cached snapshot, e.g. after a `license.changed` event. */
+  invalidate(venueId) {
+    this.cache.delete(venueId);
+  }
+  isFresh(entry) {
+    const now = Date.now();
+    const expired = entry.snapshot !== null && now >= Date.parse(entry.snapshot.validUntil);
+    return !expired && now - entry.checkedAt < this.options.cacheTtlMs;
+  }
+  refresh(venueId, cached) {
+    const pending = this.inFlight.get(venueId);
+    if (pending) return pending;
+    const request = this.fetchEntry(venueId, cached).finally(() => this.inFlight.delete(venueId));
+    this.inFlight.set(venueId, request);
+    return request;
+  }
+  async fetchEntry(venueId, cached) {
+    const headers = {
+      authorization: `Bearer ${this.options.serviceKey}`
+    };
+    if (cached?.etag) headers["if-none-match"] = cached.etag;
+    const url = `${this.options.baseUrl}/v1/entitlements?venueId=${venueId}`;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        const response = await this.options.fetch(url, {
+          headers,
+          signal: AbortSignal.timeout(this.options.timeoutMs)
+        });
+        const entry = await this.toEntry(response, cached);
+        if (entry) {
+          this.cache.set(venueId, entry);
+          return entry;
+        }
+        if (response.status < 500) {
+          this.report(new Error(`License service answered ${response.status} for venue ${venueId}`));
+          return UNREACHABLE;
+        }
+      } catch (error) {
+        if (attempt === 2) this.report(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    return UNREACHABLE;
+  }
+  async toEntry(response, cached) {
+    const checkedAt = Date.now();
+    if (response.status === 304 && cached) return {
+      ...cached,
+      checkedAt
+    };
+    if (response.status === 404) return {
+      snapshot: null,
+      etag: null,
+      checkedAt
+    };
+    if (!response.ok) return null;
+    return {
+      snapshot: await response.json(),
+      etag: response.headers.get("etag"),
+      checkedAt
+    };
+  }
+  report(error) {
+    this.options.onError?.(error);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LicenseClient
+});

package/dist/index.d.cts

@@ -0,0 +1,117 @@
+type ProductCode = string;
+type FeatureCode = string;
+interface Rate {
+    bps: number;
+    fixedMinor: number;
+}
+interface Rates {
+    pos: Rate;
+    online: Rate;
+    kiosk: Rate;
+    includeTips: boolean;
+}
+
+type LicenseState = "trial" | "active" | "grace" | "start" | "suspended" | "terminated" | "canceled";
+type PaymentMethodStatus = "ok" | "missing" | "failing";
+type PaymentsMode = "munchi" | "external";
+type PaymentsStatus = "not_started" | "submitted" | "pre_check" | "in_review" | "action_required" | "approved" | "live" | "rejected" | "restricted";
+type SuspensionReason = "misconduct" | "fraud_suspected" | "chargebacks" | "legal_request" | "terms_breach" | "customer_request" | "other";
+interface Suspension {
+    reason: SuspensionReason;
+    mode: "read_only" | "off";
+    since: string;
+    message: string;
+}
+type UsageState = "ok" | "warning" | "over" | "waiting_for_card" | "budget_reached";
+interface SnapshotUsage {
+    used: number;
+    included: number | null;
+    percent: number | null;
+    state: UsageState;
+    overageUnits: number;
+    overageProduct: ProductCode | null;
+    overageCostMinor: number;
+}
+type PriceSource = "catalog" | "contract" | "license";
+interface SnapshotItem {
+    productCode: ProductCode;
+    quantity: number;
+    priceMinor: number;
+    priceSource: PriceSource;
+}
+type RateSource = "catalog" | "contract" | "license";
+interface Snapshot {
+    schemaVersion: number;
+    v: number;
+    catalogVersion: number;
+    catalogFrozen: boolean;
+    priceVersion: number;
+    account: string;
+    location: string;
+    venueId: number | null;
+    plan: ProductCode;
+    state: LicenseState;
+    items: SnapshotItem[];
+    features: FeatureCode[];
+    limits: Record<string, number | null>;
+    rates: Rates & {
+        source: RateSource;
+    };
+    settings: Record<string, boolean>;
+    usage: Record<string, SnapshotUsage>;
+    paymentMethod: PaymentMethodStatus;
+    paymentsMode: PaymentsMode;
+    paymentsStatus: PaymentsStatus;
+    spendingBudget: {
+        limitMinor: number | null;
+        usedMinor: number;
+    };
+    suspension: Suspension | null;
+    validUntil: string;
+    computedAt: string;
+}
+
+interface LicenseClientOptions {
+    /** e.g. `https://one-license-api-prod-749434767588.europe-west3.run.app` */
+    baseUrl: string;
+    serviceKey: string;
+    /** How long a snapshot is used before asking the server again (an ETag check, usually a 304). */
+    cacheTtlMs?: number;
+    /** How long a snapshot keeps being used while the server can't be reached. */
+    maxStaleMs?: number;
+    timeoutMs?: number;
+    /** `report`: `can()` always allows and calls `onDenied` for what `enforce` would block. */
+    mode?: "enforce" | "report";
+    onDenied?: (event: DeniedEvent) => void;
+    onError?: (error: Error) => void;
+    fetch?: typeof fetch;
+}
+interface DeniedEvent {
+    venueId: number;
+    feature: string;
+    reason: "not_licensed" | "unknown_venue";
+}
+declare class LicenseClient {
+    private readonly cache;
+    private readonly inFlight;
+    private readonly options;
+    constructor(options: LicenseClientOptions);
+    /**
+     * The venue's snapshot, or `null` if the license service doesn't know the venue.
+     * `undefined` means the service couldn't be reached and nothing usable is cached.
+     */
+    entitlements(venueId: number): Promise<Snapshot | null | undefined>;
+    /** Never blocks a venue because the license service is down: unknown state allows. */
+    can(venueId: number, feature: string): Promise<boolean>;
+    /** `null` = unlimited, `undefined` = no such limit or no snapshot. */
+    limit(venueId: number, key: string): Promise<number | null | undefined>;
+    /** Drop the cached snapshot, e.g. after a `license.changed` event. */
+    invalidate(venueId: number): void;
+    private isFresh;
+    private refresh;
+    private fetchEntry;
+    private toEntry;
+    private report;
+}
+
+export { type DeniedEvent, LicenseClient, type LicenseClientOptions, type Snapshot };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+type ProductCode = string;
+type FeatureCode = string;
+interface Rate {
+    bps: number;
+    fixedMinor: number;
+}
+interface Rates {
+    pos: Rate;
+    online: Rate;
+    kiosk: Rate;
+    includeTips: boolean;
+}
+
+type LicenseState = "trial" | "active" | "grace" | "start" | "suspended" | "terminated" | "canceled";
+type PaymentMethodStatus = "ok" | "missing" | "failing";
+type PaymentsMode = "munchi" | "external";
+type PaymentsStatus = "not_started" | "submitted" | "pre_check" | "in_review" | "action_required" | "approved" | "live" | "rejected" | "restricted";
+type SuspensionReason = "misconduct" | "fraud_suspected" | "chargebacks" | "legal_request" | "terms_breach" | "customer_request" | "other";
+interface Suspension {
+    reason: SuspensionReason;
+    mode: "read_only" | "off";
+    since: string;
+    message: string;
+}
+type UsageState = "ok" | "warning" | "over" | "waiting_for_card" | "budget_reached";
+interface SnapshotUsage {
+    used: number;
+    included: number | null;
+    percent: number | null;
+    state: UsageState;
+    overageUnits: number;
+    overageProduct: ProductCode | null;
+    overageCostMinor: number;
+}
+type PriceSource = "catalog" | "contract" | "license";
+interface SnapshotItem {
+    productCode: ProductCode;
+    quantity: number;
+    priceMinor: number;
+    priceSource: PriceSource;
+}
+type RateSource = "catalog" | "contract" | "license";
+interface Snapshot {
+    schemaVersion: number;
+    v: number;
+    catalogVersion: number;
+    catalogFrozen: boolean;
+    priceVersion: number;
+    account: string;
+    location: string;
+    venueId: number | null;
+    plan: ProductCode;
+    state: LicenseState;
+    items: SnapshotItem[];
+    features: FeatureCode[];
+    limits: Record<string, number | null>;
+    rates: Rates & {
+        source: RateSource;
+    };
+    settings: Record<string, boolean>;
+    usage: Record<string, SnapshotUsage>;
+    paymentMethod: PaymentMethodStatus;
+    paymentsMode: PaymentsMode;
+    paymentsStatus: PaymentsStatus;
+    spendingBudget: {
+        limitMinor: number | null;
+        usedMinor: number;
+    };
+    suspension: Suspension | null;
+    validUntil: string;
+    computedAt: string;
+}
+
+interface LicenseClientOptions {
+    /** e.g. `https://one-license-api-prod-749434767588.europe-west3.run.app` */
+    baseUrl: string;
+    serviceKey: string;
+    /** How long a snapshot is used before asking the server again (an ETag check, usually a 304). */
+    cacheTtlMs?: number;
+    /** How long a snapshot keeps being used while the server can't be reached. */
+    maxStaleMs?: number;
+    timeoutMs?: number;
+    /** `report`: `can()` always allows and calls `onDenied` for what `enforce` would block. */
+    mode?: "enforce" | "report";
+    onDenied?: (event: DeniedEvent) => void;
+    onError?: (error: Error) => void;
+    fetch?: typeof fetch;
+}
+interface DeniedEvent {
+    venueId: number;
+    feature: string;
+    reason: "not_licensed" | "unknown_venue";
+}
+declare class LicenseClient {
+    private readonly cache;
+    private readonly inFlight;
+    private readonly options;
+    constructor(options: LicenseClientOptions);
+    /**
+     * The venue's snapshot, or `null` if the license service doesn't know the venue.
+     * `undefined` means the service couldn't be reached and nothing usable is cached.
+     */
+    entitlements(venueId: number): Promise<Snapshot | null | undefined>;
+    /** Never blocks a venue because the license service is down: unknown state allows. */
+    can(venueId: number, feature: string): Promise<boolean>;
+    /** `null` = unlimited, `undefined` = no such limit or no snapshot. */
+    limit(venueId: number, key: string): Promise<number | null | undefined>;
+    /** Drop the cached snapshot, e.g. after a `license.changed` event. */
+    invalidate(venueId: number): void;
+    private isFresh;
+    private refresh;
+    private fetchEntry;
+    private toEntry;
+    private report;
+}
+
+export { type DeniedEvent, LicenseClient, type LicenseClientOptions, type Snapshot };

package/dist/index.js

@@ -0,0 +1,120 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/license-client.ts
+var UNREACHABLE = /* @__PURE__ */ Symbol("unreachable");
+var LicenseClient = class {
+  static {
+    __name(this, "LicenseClient");
+  }
+  cache = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  options;
+  constructor(options) {
+    this.options = {
+      cacheTtlMs: 6e4,
+      maxStaleMs: 24 * 60 * 6e4,
+      timeoutMs: 2e3,
+      mode: "enforce",
+      fetch: globalThis.fetch,
+      ...options,
+      baseUrl: options.baseUrl.replace(/\/+$/, "")
+    };
+  }
+  /**
+  * The venue's snapshot, or `null` if the license service doesn't know the venue.
+  * `undefined` means the service couldn't be reached and nothing usable is cached.
+  */
+  async entitlements(venueId) {
+    const cached = this.cache.get(venueId);
+    if (cached && this.isFresh(cached)) return cached.snapshot;
+    const refreshed = await this.refresh(venueId, cached);
+    if (refreshed !== UNREACHABLE) return refreshed.snapshot;
+    if (cached && Date.now() - cached.checkedAt < this.options.maxStaleMs) return cached.snapshot;
+    return void 0;
+  }
+  /** Never blocks a venue because the license service is down: unknown state allows. */
+  async can(venueId, feature) {
+    const snapshot = await this.entitlements(venueId);
+    if (snapshot === void 0) return true;
+    const allowed = snapshot?.features.includes(feature) ?? false;
+    if (allowed) return true;
+    this.options.onDenied?.({
+      venueId,
+      feature,
+      reason: snapshot === null ? "unknown_venue" : "not_licensed"
+    });
+    return this.options.mode === "report";
+  }
+  /** `null` = unlimited, `undefined` = no such limit or no snapshot. */
+  async limit(venueId, key) {
+    return (await this.entitlements(venueId))?.limits[key];
+  }
+  /** Drop the cached snapshot, e.g. after a `license.changed` event. */
+  invalidate(venueId) {
+    this.cache.delete(venueId);
+  }
+  isFresh(entry) {
+    const now = Date.now();
+    const expired = entry.snapshot !== null && now >= Date.parse(entry.snapshot.validUntil);
+    return !expired && now - entry.checkedAt < this.options.cacheTtlMs;
+  }
+  refresh(venueId, cached) {
+    const pending = this.inFlight.get(venueId);
+    if (pending) return pending;
+    const request = this.fetchEntry(venueId, cached).finally(() => this.inFlight.delete(venueId));
+    this.inFlight.set(venueId, request);
+    return request;
+  }
+  async fetchEntry(venueId, cached) {
+    const headers = {
+      authorization: `Bearer ${this.options.serviceKey}`
+    };
+    if (cached?.etag) headers["if-none-match"] = cached.etag;
+    const url = `${this.options.baseUrl}/v1/entitlements?venueId=${venueId}`;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        const response = await this.options.fetch(url, {
+          headers,
+          signal: AbortSignal.timeout(this.options.timeoutMs)
+        });
+        const entry = await this.toEntry(response, cached);
+        if (entry) {
+          this.cache.set(venueId, entry);
+          return entry;
+        }
+        if (response.status < 500) {
+          this.report(new Error(`License service answered ${response.status} for venue ${venueId}`));
+          return UNREACHABLE;
+        }
+      } catch (error) {
+        if (attempt === 2) this.report(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    return UNREACHABLE;
+  }
+  async toEntry(response, cached) {
+    const checkedAt = Date.now();
+    if (response.status === 304 && cached) return {
+      ...cached,
+      checkedAt
+    };
+    if (response.status === 404) return {
+      snapshot: null,
+      etag: null,
+      checkedAt
+    };
+    if (!response.ok) return null;
+    return {
+      snapshot: await response.json(),
+      etag: response.headers.get("etag"),
+      checkedAt
+    };
+  }
+  report(error) {
+    this.options.onError?.(error);
+  }
+};
+export {
+  LicenseClient
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@munchi_oy/license-sdk",
+  "version": "0.1.0",
+  "description": "Client for the Munchi license service: cached entitlements and feature checks per venue",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gomunchi/one-license.git",
+    "directory": "packages/license-sdk"
+  },
+  "devDependencies": {
+    "@munchi_oy/license-core": "0.1.0",
+    "@swc/core": "1.16.12",
+    "@swc/jest": "0.2.39",
+    "@types/jest": "30.0.0",
+    "jest": "30.5.2",
+    "tsup": "8.5.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.build.json --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:unit": "jest --config jest.config.cjs"
+  }
+}