@guuey/state 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Public types for `@guuey/state`.
+ *
+ * The library is intentionally narrow — it's a KV scoped per
+ * `(user, mcp)`, not a database. See `docs/principles/mcp-hosting-policy.md`
+ * for the rationale: scoped primitives let MCPs hold light state
+ * (idempotency, counters, small per-user prefs) without making guuey
+ * a backend-as-a-service. Hard caps are the product.
+ */
+/**
+ * Bundle of identifiers that scopes every operation to one
+ * `(user, mcp)` namespace. The library never reads these from
+ * env or globals at call time; consumers either pass them
+ * explicitly to `createGuueyState` or set them via
+ * `withGuueyContext` (see `./context`).
+ *
+ * `userId` is the end-user's guuey identity (Cognito sub, or the
+ * platform-derived id for BYO-auth users). `mcpId` is the MCP
+ * server's stable identifier (the deploy's app id).
+ *
+ * **Trust model (spec §3):** the hosted CLIENT binding (`HttpKv`)
+ * and the server (`stateApi`, the actual verifier) both ship. The
+ * server authenticates the federation-minted Bearer JWT and
+ * derives `userId` (the `sub` claim) + `mcpId` (hash of the
+ * canonicalized `aud` URL, see `mcpIdFromResourceUrl`)
+ * AUTHORITATIVELY server-side — the `context` this package puts on
+ * the wire is advisory-must-match, never trusted on its own. An MCP
+ * can only present tokens guuey itself issued it, so a compromised
+ * MCP's blast radius is its own app's scopes, across its own calling
+ * users — never another app's. Tokens minted for guest sessions
+ * (`issuerAuthMode: 'anonymous'`) are rejected: guests get no
+ * durable scope (mirrors the GuueyFS rule). `ScopeContext` itself
+ * stays caller-asserted at the type level — `scopeFromAuthorization`
+ * decodes without verifying, same as the in-memory binding always
+ * has; verification is the server's job, not this package's.
+ */
+export interface ScopeContext {
+    readonly userId: string;
+    readonly mcpId: string;
+    /**
+     * The inbound Bearer JWT guuey sent this MCP server (hosted binding
+     * only; in-memory ignores it). Obtain via `scopeFromAuthorization`.
+     */
+    readonly token?: string;
+}
+/**
+ * Per-operation options for `set`. TTL is REQUIRED at the type
+ * level — there is no "permanent" key in guuey-scoped KV. If
+ * the dev wants persistence, they pick a long TTL explicitly.
+ * Keeps the platform's storage costs bounded and forces the
+ * dev to think about expiry.
+ *
+ * `ttl` is in seconds. Hard cap: 90 days (60 * 60 * 24 * 90).
+ * Longer-lived data should live in the user's own SaaS via
+ * mcp-proxy credential brokering — that pattern is preferred
+ * for any "meaningful user data" anyway (best privacy posture).
+ */
+export interface SetOptions {
+    /** TTL in seconds. Max 90 days. */
+    readonly ttl: number;
+}
+/**
+ * Per-key counter options. Atomic increment is the one
+ * "transaction-like" operation the API offers — no MULTI/EXEC,
+ * no CAS on arbitrary values. Counters cover the common case
+ * (rate limits, generated-id sequences) without opening the door
+ * to "build any app on guuey."
+ */
+export interface IncrementOptions {
+    /** Amount to add (default 1). May be negative. */
+    readonly by?: number;
+    /** TTL in seconds for the (possibly fresh) counter key. */
+    readonly ttl: number;
+}
+/**
+ * One page of a `keys()` listing. `cursor` is present when more
+ * keys remain — pass it back to `keys()` to continue. Treat it as
+ * an opaque token (its format may differ between bindings).
+ */
+export interface KeysPage {
+    readonly keys: string[];
+    readonly cursor?: string;
+}
+/**
+ * Snapshot of the current scope's storage usage. Returned by
+ * `kv.scope()`. Cheap to call; pulled from the platform on each
+ * invocation (no client-side caching) so quota checks before
+ * a write reflect the live state.
+ */
+export interface ScopeInfo {
+    readonly userId: string;
+    readonly mcpId: string;
+    /**
+     * Bytes used in this `(user, mcp)` scope — UTF-8 bytes of every
+     * live key PLUS its JSON-encoded value. Keys count because they
+     * are storage too: a scope of 1 KiB keys with 1-byte values is
+     * not "empty".
+     */
+    readonly usedBytes: number;
+    /** Hard cap for the scope. Today: 1 MiB. */
+    readonly limitBytes: number;
+    /** Distinct keys in this scope. */
+    readonly keyCount: number;
+}
+/**
+ * The KV interface every binding implements (in-memory for local
+ * dev, HTTP for hosted pods). Consumer code only ever sees this
+ * shape — they never touch the underlying transport.
+ *
+ * All methods are async even when they could be sync — keeps the
+ * shape stable across local-vs-hosted bindings and discourages
+ * "sync KV in the hot path" patterns that hide latency.
+ *
+ * Type parameter `T` on `get`/`set`: a structural hint, NOT a
+ * runtime check. The library JSON-serializes on write and parses
+ * on read. If the read shape doesn't match the type parameter,
+ * you get a wrongly-typed value with no warning. Pair with a
+ * schema (zod, valibot, …) at the call site if runtime safety
+ * matters.
+ */
+export interface Kv {
+    /** Read a key. Returns `undefined` if absent or expired. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Write a key. TTL is required (no permanent keys).
+     *
+     * Values must be JSON-serializable: top-level `undefined`,
+     * functions, symbols, `BigInt`, and circular structures throw
+     * `InvalidArgumentError`. Standard JSON semantics otherwise
+     * apply — `NaN`/`Infinity` serialize as `null`, and nested
+     * `undefined`/function properties are dropped, exactly as
+     * `JSON.stringify` does.
+     */
+    set<T = unknown>(key: string, value: T, opts: SetOptions): Promise<void>;
+    /** Delete a key. No-op if absent. */
+    delete(key: string): Promise<void>;
+    /** Cheap existence check without deserializing the value. */
+    has(key: string): Promise<boolean>;
+    /**
+     * List keys in this scope, optionally filtered by prefix, in
+     * lexicographic order. Pages of up to 1000 keys; pass the
+     * returned `cursor` back to continue. Use this for diagnostics
+     * and small housekeeping; do NOT use it as a query engine. A
+     * scope that needs to "find all keys matching pattern X across
+     * millions of entries" wants a real database (Case B in the
+     * hosting policy).
+     */
+    keys(opts?: {
+        prefix?: string;
+        limit?: number;
+        /** Opaque continuation token from a previous page. */
+        cursor?: string;
+    }): Promise<KeysPage>;
+    /**
+     * Atomic increment. Creates the key (initialized to 0) if
+     * missing, then adds `by` (default 1) and returns the new
+     * value. Useful for rate-limit counters, generated-id
+     * sequences, simple analytics.
+     *
+     * Counters are integer-only: `by` must be a safe integer
+     * (`InvalidArgumentError` otherwise), and a key holding a
+     * non-number value throws `TypeMismatchError`.
+     *
+     * The TTL is reset on every increment to the value passed —
+     * idle counters expire naturally.
+     */
+    increment(key: string, opts: IncrementOptions): Promise<number>;
+    /** Inverse of `increment`. Same semantics. */
+    decrement(key: string, opts: IncrementOptions): Promise<number>;
+    /**
+     * Bulk read. Missing keys map to `undefined`. Cap: 100 keys per
+     * call (`InvalidArgumentError` beyond) — batch if you need more.
+     */
+    mget<T = unknown>(keys: string[]): Promise<Record<string, T | undefined>>;
+    /**
+     * Snapshot of current scope usage. Use this BEFORE a large
+     * write to fail fast if you're near the quota cap rather than
+     * eating a `QuotaExceededError` mid-batch.
+     */
+    scope(): Promise<ScopeInfo>;
+}
+/**
+ * Options for `createGuueyState`. Binding selection:
+ *
+ * 1. If `bindingUrl` (or the `GUUEY_KV_URL` env) is set → the hosted
+ *    HTTP binding (`HttpKv`). Requires a token — see `authToken`
+ *    below — or `createGuueyState` throws `InvalidContextError`
+ *    rather than silently handing back a non-durable in-memory store
+ *    to a caller who asked for the hosted one.
+ * 2. Otherwise → in-memory binding (one-time warning).
+ *
+ * The in-memory binding is right for unit tests + local development.
+ * guuey-hosted and colocated MCP servers get `GUUEY_KV_URL` injected
+ * at boot and pick up the hosted binding unchanged; a dev-hosted
+ * `external` server sets it itself. No token env var is injected —
+ * the auth token is the inbound federation Bearer JWT, obtained per
+ * request via `scopeFromAuthorization` (`context.token`).
+ */
+export interface CreateGuueyStateOptions {
+    /** Scope identity. Required. */
+    readonly context: ScopeContext;
+    /** Override the binding URL (defaults to `GUUEY_KV_URL` env). */
+    readonly bindingUrl?: string;
+    /**
+     * Override the auth token (defaults to `GUUEY_KV_TOKEN` env, then
+     * `context.token`). Normally you never set this: the token is the
+     * inbound federation Bearer JWT and arrives via
+     * `scopeFromAuthorization` as `context.token`. `GUUEY_KV_TOKEN` /
+     * `authToken` are manual escape hatches (scripts, tests) — nothing
+     * on the platform injects them. See the `ScopeContext` trust model:
+     * the hosted KV API derives the mcp scope from this token
+     * server-side rather than trusting the caller's `mcpId`. Overrides
+     * `context.token` when both are set.
+     */
+    readonly authToken?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Public types for `@guuey/state`.
+ *
+ * The library is intentionally narrow — it's a KV scoped per
+ * `(user, mcp)`, not a database. See `docs/principles/mcp-hosting-policy.md`
+ * for the rationale: scoped primitives let MCPs hold light state
+ * (idempotency, counters, small per-user prefs) without making guuey
+ * a backend-as-a-service. Hard caps are the product.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/validate.d.ts

@@ -0,0 +1,19 @@
+export declare const SCOPE_LIMIT_BYTES: number;
+export declare const VALUE_LIMIT_BYTES: number;
+export declare const KEY_LIMIT_BYTES = 1024;
+export declare const TTL_MAX_SECONDS: number;
+export declare const MGET_LIMIT = 100;
+export declare const VALID_KEY: RegExp;
+export declare function validateKey(key: string): void;
+export declare function validateTtl(ttl: number): void;
+/**
+ * JSON-encode a value for storage, converting every serialization
+ * failure into the library's typed error. `JSON.stringify` returns
+ * the VALUE `undefined` (not a string) for top-level `undefined`,
+ * functions, and symbols, and throws natively for circular
+ * structures and `BigInt` — none of which may escape as a bare
+ * `TypeError` (the error contract promises `GuueyStateError`
+ * subclasses from every failable operation).
+ */
+export declare function encodeValue(key: string, value: unknown): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,eAAe,QAAoB,CAAC;AACjD,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,SAAS,QAAyB,CAAC;AAEhD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAa7C;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAW7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAiB/D"}

package/dist/validate.js

@@ -0,0 +1,60 @@
+/**
+ * Shared key/TTL/value validation + cap constants.
+ *
+ * Both bindings (in-memory, hosted HTTP) enforce the exact same
+ * contract on keys/TTLs/values before touching storage — living here
+ * once means the two implementations can never drift on what counts
+ * as a valid key, TTL, or JSON-serializable value.
+ */
+import { InvalidArgumentError, InvalidKeyError, InvalidTtlError } from "./errors.js";
+export const SCOPE_LIMIT_BYTES = 1 * 1024 * 1024; // 1 MiB
+export const VALUE_LIMIT_BYTES = 64 * 1024; // 64 KiB
+export const KEY_LIMIT_BYTES = 1024;
+export const TTL_MAX_SECONDS = 60 * 60 * 24 * 90; // 90 days
+export const MGET_LIMIT = 100;
+export const VALID_KEY = /^[A-Za-z0-9_.:\-/]+$/;
+export function validateKey(key) {
+    if (key.length === 0) {
+        throw new InvalidKeyError(key, "must be non-empty");
+    }
+    if (Buffer.byteLength(key, "utf8") > KEY_LIMIT_BYTES) {
+        throw new InvalidKeyError(key, `must be <= ${KEY_LIMIT_BYTES} bytes`);
+    }
+    if (!VALID_KEY.test(key)) {
+        throw new InvalidKeyError(key, "may only contain ASCII letters, digits, and `_.:-/`");
+    }
+}
+export function validateTtl(ttl) {
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+        throw new InvalidTtlError(ttl, "must be a positive finite number");
+    }
+    if (ttl > TTL_MAX_SECONDS) {
+        throw new InvalidTtlError(ttl, `must be <= ${TTL_MAX_SECONDS} seconds (90 days). ` +
+            `Long-lived data belongs in user-owned storage via mcp-proxy.`);
+    }
+}
+/**
+ * JSON-encode a value for storage, converting every serialization
+ * failure into the library's typed error. `JSON.stringify` returns
+ * the VALUE `undefined` (not a string) for top-level `undefined`,
+ * functions, and symbols, and throws natively for circular
+ * structures and `BigInt` — none of which may escape as a bare
+ * `TypeError` (the error contract promises `GuueyStateError`
+ * subclasses from every failable operation).
+ */
+export function encodeValue(key, value) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (err) {
+        throw new InvalidArgumentError(`value for key ${JSON.stringify(key)} is not JSON-serializable ` +
+            `(${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (json === undefined) {
+        throw new InvalidArgumentError(`value for key ${JSON.stringify(key)} is not JSON-serializable ` +
+            `(top-level undefined, function, or symbol)`);
+    }
+    return json;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,QAAQ;AAC1D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAC;AAC9B,MAAM,CAAC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEhD,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,eAAe,EAAE,CAAC;QACrD,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,cAAc,eAAe,QAAQ,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CACvB,GAAG,EACH,qDAAqD,CACtD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,kCAAkC,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,GAAG,GAAG,eAAe,EAAE,CAAC;QAC1B,MAAM,IAAI,eAAe,CACvB,GAAG,EACH,cAAc,eAAe,sBAAsB;YACjD,8DAA8D,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAc;IACrD,IAAI,IAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,oBAAoB,CAC5B,iBAAiB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,4BAA4B;YAC9D,IAAI,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,oBAAoB,CAC5B,iBAAiB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,4BAA4B;YAC9D,4CAA4C,CAC/C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@guuey/state",
+  "version": "0.1.0",
+  "description": "Open-source KV client for MCP servers hosted on guuey.com. Scoped per (user, mcp). The MCP stays stateless from its own POV while the user retains data ownership. Hard caps are the product.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/contract-suite.d.ts",
+      "import": "./dist/testing/contract-suite.js"
+    }
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "guuey",
+    "kv",
+    "key-value",
+    "storage"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/state"
+  },
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}