@q32/core 0.1.1

package/docs/evaluation.md

@@ -0,0 +1,74 @@
+# Suitability Evaluation
+
+This package was seeded from repeated infrastructure found across Erik/Q32 TypeScript projects, including `adgiro`, `bizsnipe`, `dirtsignal`, `getflight`, `graphilize`, `ipogrid`, `logtura`, `onwardtravel`, `relin`, `zura`, and the `domains/*` apps.
+
+## Replacement Matrix
+
+| Common pattern | Current module | Suitable replacement scope |
+| --- | --- | --- |
+| AI JSON helper conventions | `ai` | Standardize model request/response contracts and JSON extraction around official provider SDK calls. |
+| Typed environment helpers and app URL fallback | `env` | Replace local `getAppUrl`, required env, optional boolean, and binding guard helpers. |
+| Cloudflare binding checks | `cloudflare` | Replace repeated `DB`, `R2`, and Queue binding guard code in Workers. |
+| JSON responses, bearer/admin token checks, request body parsing | `http` | Replace repeated Worker/Hono-adjacent HTTP utility functions. |
+| Prefixed IDs, random tokens, base64url, SHA-256 | `ids` | Replace local `createId`, token, digest-key, and hash helpers. |
+| Signed session tokens and cookies | `session` | Replace small HMAC session implementations where full auth frameworks are unnecessary. |
+| Credential or provider-secret encryption | `crypto` | Replace local AES-GCM JSON encryption helpers backed by WebCrypto. |
+| D1-like database typing and explicit migrations | `d1` | Replace duplicated `D1DatabaseLike` types and simple migration runners. |
+| Postgres migration and JSON helpers | `pg` | Replace small pg migration scripts while still using official `pg` or `postgres` clients in apps. |
+| Background job table behavior | `jobs` | Replace D1 job enqueue/claim/run/requeue/succeed/fail loops in small Worker apps. |
+| Operator event recording and listing | `ops-events` | Replace repeated `ops_events` insert/list helpers. |
+| D1 fixed-window rate limits | `rate-limit` | Replace lead, login, public API, and admin throttle tables. |
+| R2 JSON payload/artifact storage | `r2-json` | Replace raw provider payload and generated artifact JSON storage helpers. |
+| SEO/static output conventions | `seo` | Replace ad hoc sitemap, robots, canonical, Open Graph, and noindex tag helpers. |
+| Email provider boundary | `email` | Standardize provider-independent send input/result shapes and address helpers. |
+| Billing plan/status checks | `billing` | Replace local plan rank and active subscription status helpers around Stripe-backed apps. |
+| Worker test helpers | `testing` | Replace small fake Queue/R2 helpers and JSON response assertions in unit tests; complements workerd/Miniflare integration tests. |
+| OAuth/MCP metadata | `oauth`, `mcp` | Replace repeated discovery metadata and API-to-tool descriptors; full OAuth token stores remain app-specific for now. |
+| API operation registries | `api` | Replace local operation registries used for OpenAPI, admin APIs, and MCP exposure. |
+
+## Current Fit
+
+The package is suitable for new Q32 Worker projects and for incremental replacement of local helpers in existing projects where the app-specific behavior is already separated from infrastructure primitives.
+
+Strong first replacement candidates:
+
+- D1-like interfaces duplicated in `relin` and `graphilize`.
+- `ops_events` helpers in `onwardtravel`, `bizsnipe`, `logtura`, and `bce.email`.
+- D1 jobs in `travelerideas`, `bizsnipe`, `logtura`, and smaller domain apps.
+- signed session, ID, token, and base64url helpers in `zura`, `relin`, `getflight`, and `adgiro`.
+- API operation metadata from `bce.email` and `relin`.
+- OAuth/MCP metadata from `getflight`, `captcha`, `ipogrid`, `relin`, and `bce.email`.
+
+## Not Yet Complete
+
+The package intentionally does not yet replace:
+
+- full app account systems
+- full OAuth authorization-code and refresh-token stores
+- Stripe billing repositories
+- Postgres job runners and migration orchestration
+- email provider clients
+- Mantine app shells or SEO page components
+- OpenAI/provider retry adapters beyond the shared request/result contracts
+- Stripe webhook verification or Checkout/session creation, which should remain on the official Stripe SDK
+- Mantine app shells or React components
+
+Those should be added only after extracting one or two real migrations from existing apps so the shared API follows production usage rather than speculation.
+
+## Verification
+
+Current local gates:
+
+- `pnpm typecheck`
+- `pnpm test:coverage`
+- `pnpm build`
+- `pnpm pack --dry-run`
+
+Coverage threshold is enforced in `vitest.config.ts` and CI runs the same gates.
+
+Current coverage after the expanded common-module pass:
+
+- Statements: 89.26%
+- Branches: 75.25%
+- Functions: 96.66%
+- Lines: 95.15%

package/docs/goal-audit.md

@@ -0,0 +1,28 @@
+# Goal Audit
+
+Objective: working Q32 core libraries, with the common libraries discussed in the project inventory, a public repo at the `q32llc` org, working CI/CD, strong types and good test coverage, evaluated as suitable to replace much common code in existing projects.
+
+## Proven Complete
+
+| Requirement | Evidence |
+| --- | --- |
+| Public repo under `q32llc` | `https://github.com/q32llc/q32-core`, public, default branch `main`. |
+| Working local package | `pnpm build` succeeds and `pnpm pack --dry-run` produces a clean tarball. |
+| Strong TypeScript types | `pnpm typecheck` succeeds under `strict` TypeScript with generated declarations. |
+| Good test coverage | `pnpm test:coverage` succeeds with enforced thresholds; latest local coverage is 89.26% statements, 75.25% branches, 96.66% functions, 95.15% lines. |
+| Working CI | GitHub Actions CI passes on `main` and runs install, typecheck, coverage, build, and pack dry run. |
+| Common code surfaces | Modules exist for `api`, `ai`, `billing`, `cloudflare`, `crypto`, `d1`, `email`, `env`, `http`, `ids`, `jobs`, `mcp`, `oauth`, `ops-events`, `pg`, `r2-json`, `rate-limit`, `seo`, `session`, `testing`, and `time`. |
+| Suitability evaluation | `docs/evaluation.md` maps modules to common patterns found in existing projects and identifies first replacement candidates. |
+| Consumer install smoke | Packed tarball was installed into a clean temp project and imported successfully from `@q32/core`. |
+
+## Incomplete Or Externally Blocked
+
+| Requirement | Status |
+| --- | --- |
+| npm package published | Not complete. Local `npm whoami` returns `E401`, and `@q32/core` does not exist on npm yet. |
+| npm publish step in CD | Workflow exists and skips safely when `NPM_TOKEN` is absent. Actual npm publishing cannot be proven until npm publishing is configured through `NPM_TOKEN` or npm trusted publishing for this repo/package. |
+| Proven replacement in existing apps | Not complete. The library is evaluated as suitable, but no existing app has been migrated to consume it yet. |
+
+## Recommended Next Proof Step
+
+Migrate one low-risk repeated slice in an existing app, such as replacing the duplicated `D1DatabaseLike` type in `relin` or `graphilize`, or replacing `ops_events` helpers in `onwardtravel`. That will validate the public API against production code and expose any ergonomics issues before broad adoption.

package/package.json

@@ -0,0 +1,129 @@
+{
+  "name": "@q32/core",
+  "version": "0.1.1",
+  "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/q32llc/q32-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/q32llc/q32-core/issues"
+  },
+  "homepage": "https://github.com/q32llc/q32-core#readme",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "default": "./dist/ai.js"
+    },
+    "./billing": {
+      "types": "./dist/billing.d.ts",
+      "default": "./dist/billing.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "default": "./dist/cloudflare.js"
+    },
+    "./crypto": {
+      "types": "./dist/crypto.d.ts",
+      "default": "./dist/crypto.js"
+    },
+    "./d1": {
+      "types": "./dist/d1.d.ts",
+      "default": "./dist/d1.js"
+    },
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "default": "./dist/email.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "default": "./dist/env.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./ids": {
+      "types": "./dist/ids.d.ts",
+      "default": "./dist/ids.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "default": "./dist/jobs.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    },
+    "./oauth": {
+      "types": "./dist/oauth.d.ts",
+      "default": "./dist/oauth.js"
+    },
+    "./ops-events": {
+      "types": "./dist/ops-events.d.ts",
+      "default": "./dist/ops-events.js"
+    },
+    "./pg": {
+      "types": "./dist/pg.d.ts",
+      "default": "./dist/pg.js"
+    },
+    "./r2-json": {
+      "types": "./dist/r2-json.d.ts",
+      "default": "./dist/r2-json.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit.d.ts",
+      "default": "./dist/rate-limit.js"
+    },
+    "./seo": {
+      "types": "./dist/seo.d.ts",
+      "default": "./dist/seo.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "default": "./dist/session.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./time": {
+      "types": "./dist/time.d.ts",
+      "default": "./dist/time.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260606.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}