@munchi_oy/license-sdk 0.1.0 → 0.2.1

package/README.md

@@ -13,7 +13,8 @@ const license = new LicenseClient({
   onError: (e) => logger.error(e, "license service unreachable"),
 });
 
-if (await license.can(venueId, "kiosk")) { /* … */ }
+if (await license.can(venueId, "kiosk")) { /* may use it now */ }
+if (await license.canView(venueId, "reports")) { /* may still see its data (read-only suspension) */ }
 const kiosks = await license.limit(venueId, "kiosks"); // number, null = unlimited
 const snapshot = await license.entitlements(venueId); // full snapshot, null = unknown venue
 ```
@@ -22,8 +23,10 @@ const snapshot = await license.entitlements(venueId); // full snapshot, null = u
 |---|---|
 | 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 |
+| Venue unknown to the license service | allows, and calls `onDenied` with `unknown_venue` (never blocks a venue we forgot to set up) |
+| Suspended | `can()` is false; `canView()` stays true for a `read_only` suspension, false for `off` |
 | 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 |
+| `mode: "enforce"` | `can()` returns `false` for features the venue doesn't have, or while it is suspended |
 
 Call `invalidate(venueId)` when you receive a `license.changed` event.

package/dist/index.cjs

@@ -57,16 +57,40 @@ var LicenseClient = class {
     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. */
+  /**
+  * May the venue use the feature now (create orders, take payments…)? False while suspended.
+  * Never blocks because of us: when the service is down, or doesn't know the venue yet
+  * (reported through `onDenied` as `unknown_venue`), it allows.
+  */
   async can(venueId, feature) {
+    return this.check(venueId, feature, false);
+  }
+  /**
+  * May the venue still see the feature's existing data? Like `can()`, but also true during a
+  * `read_only` suspension, when nothing new is allowed but history stays visible.
+  */
+  async canView(venueId, feature) {
+    return this.check(venueId, feature, true);
+  }
+  async check(venueId, feature, view) {
     const snapshot = await this.entitlements(venueId);
     if (snapshot === void 0) return true;
-    const allowed = snapshot?.features.includes(feature) ?? false;
-    if (allowed) return true;
+    if (snapshot === null) {
+      this.options.onDenied?.({
+        venueId,
+        feature,
+        reason: "unknown_venue"
+      });
+      return true;
+    }
+    const readOnly = snapshot.suspension?.mode === "read_only";
+    const active = snapshot.state !== "suspended" || view && readOnly;
+    const licensed = snapshot.features.includes(feature);
+    if (licensed && active) return true;
     this.options.onDenied?.({
       venueId,
       feature,
-      reason: snapshot === null ? "unknown_venue" : "not_licensed"
+      reason: licensed ? "suspended" : "not_licensed"
     });
     return this.options.mode === "report";
   }

package/dist/index.d.cts

@@ -1,15 +1,5 @@
 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";
@@ -40,6 +30,29 @@ interface SnapshotItem {
     priceSource: PriceSource;
 }
 type RateSource = "catalog" | "contract" | "license";
+interface ChannelRate {
+    bps: number;
+    fixedMinor: number;
+    source: RateSource;
+}
+type IsvSource = "calculated" | "manual";
+interface Isv {
+    bps: number;
+    fixedMinor: number;
+    source: IsvSource;
+}
+/** A card-present channel: the fee the customer pays and Munchi's share of it on Viva. */
+interface CardChannelRate extends ChannelRate {
+    /** `null` when it can't be calculated: no Viva cost in the catalog, or a fee below it. */
+    isv: Isv | null;
+}
+interface SnapshotRates {
+    /** `null` when card payments at the venue don't go through Munchi (`paymentsMode: "external"`). */
+    pos: CardChannelRate | null;
+    kiosk: CardChannelRate | null;
+    online: ChannelRate;
+    includeTips: boolean;
+}
 interface Snapshot {
     schemaVersion: number;
     v: number;
@@ -54,9 +67,7 @@ interface Snapshot {
     items: SnapshotItem[];
     features: FeatureCode[];
     limits: Record<string, number | null>;
-    rates: Rates & {
-        source: RateSource;
-    };
+    rates: SnapshotRates;
     settings: Record<string, boolean>;
     usage: Record<string, SnapshotUsage>;
     paymentMethod: PaymentMethodStatus;
@@ -89,7 +100,7 @@ interface LicenseClientOptions {
 interface DeniedEvent {
     venueId: number;
     feature: string;
-    reason: "not_licensed" | "unknown_venue";
+    reason: "not_licensed" | "suspended" | "unknown_venue";
 }
 declare class LicenseClient {
     private readonly cache;
@@ -101,8 +112,18 @@ declare class LicenseClient {
      * `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. */
+    /**
+     * May the venue use the feature now (create orders, take payments…)? False while suspended.
+     * Never blocks because of us: when the service is down, or doesn't know the venue yet
+     * (reported through `onDenied` as `unknown_venue`), it allows.
+     */
     can(venueId: number, feature: string): Promise<boolean>;
+    /**
+     * May the venue still see the feature's existing data? Like `can()`, but also true during a
+     * `read_only` suspension, when nothing new is allowed but history stays visible.
+     */
+    canView(venueId: number, feature: string): Promise<boolean>;
+    private check;
     /** `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. */

package/dist/index.d.ts

@@ -1,15 +1,5 @@
 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";
@@ -40,6 +30,29 @@ interface SnapshotItem {
     priceSource: PriceSource;
 }
 type RateSource = "catalog" | "contract" | "license";
+interface ChannelRate {
+    bps: number;
+    fixedMinor: number;
+    source: RateSource;
+}
+type IsvSource = "calculated" | "manual";
+interface Isv {
+    bps: number;
+    fixedMinor: number;
+    source: IsvSource;
+}
+/** A card-present channel: the fee the customer pays and Munchi's share of it on Viva. */
+interface CardChannelRate extends ChannelRate {
+    /** `null` when it can't be calculated: no Viva cost in the catalog, or a fee below it. */
+    isv: Isv | null;
+}
+interface SnapshotRates {
+    /** `null` when card payments at the venue don't go through Munchi (`paymentsMode: "external"`). */
+    pos: CardChannelRate | null;
+    kiosk: CardChannelRate | null;
+    online: ChannelRate;
+    includeTips: boolean;
+}
 interface Snapshot {
     schemaVersion: number;
     v: number;
@@ -54,9 +67,7 @@ interface Snapshot {
     items: SnapshotItem[];
     features: FeatureCode[];
     limits: Record<string, number | null>;
-    rates: Rates & {
-        source: RateSource;
-    };
+    rates: SnapshotRates;
     settings: Record<string, boolean>;
     usage: Record<string, SnapshotUsage>;
     paymentMethod: PaymentMethodStatus;
@@ -89,7 +100,7 @@ interface LicenseClientOptions {
 interface DeniedEvent {
     venueId: number;
     feature: string;
-    reason: "not_licensed" | "unknown_venue";
+    reason: "not_licensed" | "suspended" | "unknown_venue";
 }
 declare class LicenseClient {
     private readonly cache;
@@ -101,8 +112,18 @@ declare class LicenseClient {
      * `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. */
+    /**
+     * May the venue use the feature now (create orders, take payments…)? False while suspended.
+     * Never blocks because of us: when the service is down, or doesn't know the venue yet
+     * (reported through `onDenied` as `unknown_venue`), it allows.
+     */
     can(venueId: number, feature: string): Promise<boolean>;
+    /**
+     * May the venue still see the feature's existing data? Like `can()`, but also true during a
+     * `read_only` suspension, when nothing new is allowed but history stays visible.
+     */
+    canView(venueId: number, feature: string): Promise<boolean>;
+    private check;
     /** `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. */

package/dist/index.js

@@ -33,16 +33,40 @@ var LicenseClient = class {
     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. */
+  /**
+  * May the venue use the feature now (create orders, take payments…)? False while suspended.
+  * Never blocks because of us: when the service is down, or doesn't know the venue yet
+  * (reported through `onDenied` as `unknown_venue`), it allows.
+  */
   async can(venueId, feature) {
+    return this.check(venueId, feature, false);
+  }
+  /**
+  * May the venue still see the feature's existing data? Like `can()`, but also true during a
+  * `read_only` suspension, when nothing new is allowed but history stays visible.
+  */
+  async canView(venueId, feature) {
+    return this.check(venueId, feature, true);
+  }
+  async check(venueId, feature, view) {
     const snapshot = await this.entitlements(venueId);
     if (snapshot === void 0) return true;
-    const allowed = snapshot?.features.includes(feature) ?? false;
-    if (allowed) return true;
+    if (snapshot === null) {
+      this.options.onDenied?.({
+        venueId,
+        feature,
+        reason: "unknown_venue"
+      });
+      return true;
+    }
+    const readOnly = snapshot.suspension?.mode === "read_only";
+    const active = snapshot.state !== "suspended" || view && readOnly;
+    const licensed = snapshot.features.includes(feature);
+    if (licensed && active) return true;
     this.options.onDenied?.({
       venueId,
       feature,
-      reason: snapshot === null ? "unknown_venue" : "not_licensed"
+      reason: licensed ? "suspended" : "not_licensed"
     });
     return this.options.mode === "report";
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@munchi_oy/license-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Client for the Munchi license service: cached entitlements and feature checks per venue",
   "type": "module",
   "main": "./dist/index.cjs",