@happ-cli/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @happ/sdk — framework-agnostic core client for the Happ feature entitlement platform.
+ *
+ * Works in any Node.js ≥18 environment: Express, Fastify, Remix, plain scripts, etc.
+ * Uses native fetch — no extra dependencies.
+ *
+ * Usage:
+ *   import { createHappClient } from "@happ/sdk"
+ *
+ *   const happ = createHappClient()  // reads HAPP_API_URL + HAPP_API_KEY from env
+ *
+ *   const result = await happ.eval("invoices", userId)
+ *   if (!result.allowed) return res.status(403).json({ error: "Access denied" })
+ *
+ *   await createInvoice(...)
+ *   await happ.increment("invoices", userId)
+ */
+export interface HappClientOptions {
+    /** Happ API base URL. Defaults to HAPP_API_URL env var or the production URL. */
+    apiUrl?: string;
+    /** Happ project API key. Defaults to HAPP_API_KEY env var. */
+    apiKey?: string;
+}
+export interface EvalResult {
+    allowed: boolean;
+    reason?: string;
+    remaining?: number;
+    effectiveSubscriberId?: string;
+}
+/** Human-readable denial messages keyed by reason code from the Happ API. */
+export declare const DENIAL_MESSAGES: Record<string, string>;
+export declare class HappClient {
+    protected readonly apiUrl: string;
+    protected readonly apiKey: string;
+    constructor(options?: HappClientOptions);
+    /** Internal fetch with auth headers pre-applied. */
+    protected request(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Evaluate whether a subscriber is allowed to use a feature.
+     * Fails open — returns `{ allowed: true }` if the API is unreachable.
+     */
+    eval(featureKey: string, subscriberId: string): Promise<EvalResult>;
+    /**
+     * Increment usage for a metered feature after a successful action.
+     * Fire-and-forget — never throws or blocks the response.
+     */
+    increment(featureKey: string, subscriberId: string): Promise<void>;
+}
+/** Create a Happ client. Options default to HAPP_API_URL and HAPP_API_KEY env vars. */
+export declare function createHappClient(options?: HappClientOptions): HappClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMlD,CAAA;AAID,qBAAa,UAAU;IACrB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBAErB,OAAO,GAAE,iBAAsB;IAK3C,oDAAoD;IACpD,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAW1E;;;OAGG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAYzE;;;OAGG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAWzE;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAExE"}

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * @happ/sdk — framework-agnostic core client for the Happ feature entitlement platform.
+ *
+ * Works in any Node.js ≥18 environment: Express, Fastify, Remix, plain scripts, etc.
+ * Uses native fetch — no extra dependencies.
+ *
+ * Usage:
+ *   import { createHappClient } from "@happ/sdk"
+ *
+ *   const happ = createHappClient()  // reads HAPP_API_URL + HAPP_API_KEY from env
+ *
+ *   const result = await happ.eval("invoices", userId)
+ *   if (!result.allowed) return res.status(403).json({ error: "Access denied" })
+ *
+ *   await createInvoice(...)
+ *   await happ.increment("invoices", userId)
+ */
+const DEFAULT_API_URL = "https://happ-api-prod.up.railway.app";
+/** Human-readable denial messages keyed by reason code from the Happ API. */
+export const DENIAL_MESSAGES = {
+    limit_exceeded: "You've reached the limit for your plan. Upgrade to continue.",
+    no_subscription: "No active subscription found.",
+    not_in_plan: "This feature is not included in your current plan.",
+    feature_not_live: "This feature is not yet available.",
+    subscription_expired: "Your subscription has expired.",
+};
+// ─── Client ───────────────────────────────────────────────────────────────────
+export class HappClient {
+    constructor(options = {}) {
+        this.apiUrl = options.apiUrl ?? process.env["HAPP_API_URL"] ?? DEFAULT_API_URL;
+        this.apiKey = options.apiKey ?? process.env["HAPP_API_KEY"] ?? "";
+    }
+    /** Internal fetch with auth headers pre-applied. */
+    request(path, init = {}) {
+        return fetch(`${this.apiUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...init.headers,
+            },
+            cache: "no-store",
+        });
+    }
+    /**
+     * Evaluate whether a subscriber is allowed to use a feature.
+     * Fails open — returns `{ allowed: true }` if the API is unreachable.
+     */
+    async eval(featureKey, subscriberId) {
+        try {
+            const res = await this.request(`/api/eval/${featureKey}?subscriberId=${encodeURIComponent(subscriberId)}`);
+            if (!res.ok)
+                return { allowed: true }; // fail open on API error
+            return res.json();
+        }
+        catch {
+            return { allowed: true }; // fail open on network error
+        }
+    }
+    /**
+     * Increment usage for a metered feature after a successful action.
+     * Fire-and-forget — never throws or blocks the response.
+     */
+    async increment(featureKey, subscriberId) {
+        try {
+            await this.request(`/api/eval/${featureKey}/increment`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ subscriberId }),
+            });
+        }
+        catch {
+            // intentionally swallowed — usage tracking must never block the user
+        }
+    }
+}
+/** Create a Happ client. Options default to HAPP_API_URL and HAPP_API_KEY env vars. */
+export function createHappClient(options) {
+    return new HappClient(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,eAAe,GAAG,sCAAsC,CAAA;AAkB9D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,cAAc,EAAQ,8DAA8D;IACpF,eAAe,EAAO,+BAA+B;IACrD,WAAW,EAAW,oDAAoD;IAC1E,gBAAgB,EAAM,oCAAoC;IAC1D,oBAAoB,EAAE,gCAAgC;CACvD,CAAA;AAED,iFAAiF;AAEjF,MAAM,OAAO,UAAU;IAIrB,YAAY,UAA6B,EAAE;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,eAAe,CAAA;QAC9E,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAA;IACnE,CAAC;IAED,oDAAoD;IAC1C,OAAO,CAAC,IAAY,EAAE,OAAoB,EAAE;QACpD,OAAO,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,EAAE;YACpC,GAAG,IAAI;YACP,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gBACtC,GAAG,IAAI,CAAC,OAAO;aAChB;YACD,KAAK,EAAE,UAA0B;SAClC,CAAC,CAAA;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,UAAkB,EAAE,YAAoB;QACjD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAC5B,aAAa,UAAU,iBAAiB,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAC3E,CAAA;YACD,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA,CAAC,yBAAyB;YAC/D,OAAO,GAAG,CAAC,IAAI,EAAyB,CAAA;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA,CAAC,6BAA6B;QACxD,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,UAAkB,EAAE,YAAoB;QACtD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,UAAU,YAAY,EAAE;gBACtD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;aACvC,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;IACH,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@happ-cli/sdk",
+  "version": "0.1.0",
+  "description": "Happ feature entitlement SDK — framework-agnostic core",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.4.5"
+  }
+}