@q32/core 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./mcp.js";
 export * from "./oauth.js";
 export * from "./ops-events.js";
 export * from "./pg.js";
+export * from "./pg-kysely.js";
 export * from "./r2-json.js";
 export * from "./rate-limit.js";
 export * from "./seo.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./mcp.js";
 export * from "./oauth.js";
 export * from "./ops-events.js";
 export * from "./pg.js";
+export * from "./pg-kysely.js";
 export * from "./r2-json.js";
 export * from "./rate-limit.js";
 export * from "./seo.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/pg-kysely.d.ts

@@ -0,0 +1,53 @@
+import { Kysely } from "kysely";
+import postgres from "postgres";
+export type PgConnectionSource = "hyperdrive" | "url" | "fallback";
+export type PgSslMode = "auto" | "disable" | "require" | "verify-ca";
+export type HyperdriveLike = {
+    connectionString?: string;
+};
+export type PgEnvLike = Record<string, unknown> & {
+    HYPERDRIVE?: HyperdriveLike;
+    PG_URL?: string;
+    PG_CA_CERT?: string;
+};
+export type ResolvedPgConnection = {
+    connectionString: string;
+    source: PgConnectionSource;
+    closeConnection: boolean;
+    caCert?: string;
+};
+export type PgConnectionOptions = {
+    hyperdriveKey?: string;
+    urlKey?: string;
+    caCertKey?: string;
+    fallbackConnectionString?: string;
+    requireConnection?: boolean;
+    closeConnection?: boolean;
+};
+export type PgClientOptions = {
+    max?: number;
+    prepare?: boolean;
+    idleTimeoutSeconds?: number;
+    connectTimeoutSeconds?: number;
+    sslMode?: PgSslMode;
+};
+export type KyselyPgOptions = PgConnectionOptions & PgClientOptions & {
+    onDestroyError?: (error: unknown) => void;
+};
+type PostgresOptions = NonNullable<Parameters<typeof postgres>[1]>;
+export declare function resolvePgConnection(env: PgEnvLike, options?: PgConnectionOptions): ResolvedPgConnection;
+export declare function postgresClientOptions(connection: Pick<ResolvedPgConnection, "connectionString" | "source" | "caCert">, options?: PgClientOptions): PostgresOptions;
+export declare function createPostgresSql(connection: ResolvedPgConnection, options?: PgClientOptions): postgres.Sql;
+export declare function createKyselyPg<Database>(env: PgEnvLike, options?: KyselyPgOptions): {
+    db: Kysely<Database>;
+    sql: postgres.Sql;
+    connection: ResolvedPgConnection;
+    destroy(): Promise<void>;
+};
+export declare function withKyselyPg<Database, Result>(env: PgEnvLike, fn: (db: Kysely<Database>, context: {
+    sql: postgres.Sql;
+    connection: ResolvedPgConnection;
+}) => Promise<Result>, options?: KyselyPgOptions): Promise<Result>;
+export declare function normalizePem(value?: string): string | undefined;
+export {};
+//# sourceMappingURL=pg-kysely.d.ts.map

package/dist/pg-kysely.d.ts.map

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

package/dist/pg-kysely.js

@@ -0,0 +1,128 @@
+import { Kysely } from "kysely";
+import { PostgresJSDialect } from "kysely-postgres-js";
+import postgres from "postgres";
+export function resolvePgConnection(env, options = {}) {
+    const hyperdriveKey = options.hyperdriveKey ?? "HYPERDRIVE";
+    const urlKey = options.urlKey ?? "PG_URL";
+    const caCertKey = options.caCertKey ?? "PG_CA_CERT";
+    const hyperdrive = env[hyperdriveKey];
+    const hyperdriveString = cleanString(hyperdrive?.connectionString);
+    if (hyperdriveString) {
+        return {
+            connectionString: hyperdriveString,
+            source: "hyperdrive",
+            closeConnection: options.closeConnection ?? false,
+        };
+    }
+    const urlString = cleanString(env[urlKey]);
+    if (urlString) {
+        return {
+            connectionString: urlString,
+            source: "url",
+            closeConnection: options.closeConnection ?? true,
+            caCert: normalizePem(cleanString(env[caCertKey])),
+        };
+    }
+    const fallback = cleanString(options.fallbackConnectionString);
+    if (fallback) {
+        return {
+            connectionString: fallback,
+            source: "fallback",
+            closeConnection: options.closeConnection ?? true,
+            caCert: normalizePem(cleanString(env[caCertKey])),
+        };
+    }
+    if (options.requireConnection ?? true) {
+        throw new Error(`${urlKey} or ${hyperdriveKey}.connectionString is required for Postgres.`);
+    }
+    return {
+        connectionString: "",
+        source: "fallback",
+        closeConnection: options.closeConnection ?? true,
+    };
+}
+export function postgresClientOptions(connection, options = {}) {
+    const clientOptions = {
+        max: options.max ?? 1,
+        prepare: options.prepare ?? false,
+        idle_timeout: options.idleTimeoutSeconds ?? 20,
+        connect_timeout: options.connectTimeoutSeconds ?? 5,
+    };
+    const ssl = resolvePgSsl(connection, options.sslMode ?? "auto");
+    if (ssl !== undefined)
+        clientOptions.ssl = ssl;
+    return clientOptions;
+}
+export function createPostgresSql(connection, options = {}) {
+    return postgres(connection.connectionString, postgresClientOptions(connection, options));
+}
+export function createKyselyPg(env, options = {}) {
+    const connection = resolvePgConnection(env, options);
+    const sql = createPostgresSql(connection, options);
+    const db = new Kysely({
+        dialect: new PostgresJSDialect({ postgres: sql }),
+    });
+    return {
+        db,
+        sql,
+        connection,
+        async destroy() {
+            try {
+                await db.destroy();
+            }
+            catch (error) {
+                options.onDestroyError?.(error);
+                if (!options.onDestroyError)
+                    throw error;
+            }
+        },
+    };
+}
+export async function withKyselyPg(env, fn, options = {}) {
+    const handle = createKyselyPg(env, options);
+    try {
+        return await fn(handle.db, { sql: handle.sql, connection: handle.connection });
+    }
+    finally {
+        if (handle.connection.closeConnection) {
+            await handle.destroy();
+        }
+    }
+}
+export function normalizePem(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.includes("\\n") ? trimmed.replace(/\\n/g, "\n") : trimmed;
+}
+function resolvePgSsl(connection, mode) {
+    if (mode === "disable")
+        return false;
+    if (mode === "require")
+        return "require";
+    if (mode === "verify-ca") {
+        if (!connection.caCert)
+            throw new Error("PG_CA_CERT is required when sslMode is verify-ca.");
+        return { ca: connection.caCert, rejectUnauthorized: true };
+    }
+    if (connection.source === "hyperdrive")
+        return false;
+    if (connection.caCert)
+        return { ca: connection.caCert, rejectUnauthorized: true };
+    if (isLocalPgUrl(connection.connectionString))
+        return false;
+    return "require";
+}
+function isLocalPgUrl(connectionString) {
+    try {
+        const host = new URL(connectionString).hostname;
+        return host === "localhost" || host === "127.0.0.1" || host === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function cleanString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+//# sourceMappingURL=pg-kysely.js.map

package/dist/pg-kysely.js.map

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

package/docs/commonality-adgiro-relin-dirtsignal.md

@@ -0,0 +1,28 @@
+# Adgiro, Relin, and DirtSignal Commonality
+
+This is the current direction for `@q32/core`: choose the best reusable pattern across the projects, then move the projects toward it.
+
+## Chosen Defaults
+
+- Postgres access should use Kysely over raw SQL once a project has long-lived relational read models. DirtSignal has the largest raw `postgres` surface today, but Relin's Kysely layer is the better long-term default because it makes schema ownership, joins, transactions, and refactors safer.
+- Cloudflare Workers should create PG clients per request, queue invocation, cron tick, or script scope. Hyperdrive owns pooling in Worker runtime; Node scripts and tests should close clients explicitly.
+- PG connection resolution should prefer Hyperdrive, then `PG_URL`, then an explicit test fallback only when the caller opts in.
+- Non-local PG should use TLS by default. A provided `PG_CA_CERT` should be normalized and used for certificate verification.
+- PG migrations should be explicit, status/dry-run capable, and separated from runtime credentials. Relin's admin/runtime split is the better default; DirtSignal's typed migration-array model is better than ad hoc SQL file parsing for application-owned schema modules.
+- D1 remains the default for small control-plane state, but shared auth, jobs, and ops-event tables should be configurable D1 modules, not app-local forks.
+
+## Core Modules To Grow
+
+- `pg-kysely`: Kysely + `postgres.js` construction, Hyperdrive/PG_URL/CA-cert policy, and scoped `withKyselyPg`.
+- `pg-migrations`: one migration runner that can consume SQL files or typed migration arrays, with status, dry-run, reset guard, and configurable migrations table.
+- `d1-auth`: configurable users/orgs/memberships/identities/magic-link/session helpers. Apps keep policy and copy; core owns token hashing, one-time consume, identity upsert, and session persistence patterns.
+- `mcp-oauth-d1`: the common OAuth client/code/token/device-flow repository used by Relin and DirtSignal, with app-provided principal lookup and entitlement policy.
+- `d1-jobs`: Adgiro's richer job driver is closer to the target than the current minimal core job helper. Core should own enqueue policies, active locks, concurrency keys, delayed requeue, stale-running recovery, and linked ops events.
+- `queue`: a typed Cloudflare Queue publisher/consumer adapter with inline mode for tests and local single-process execution.
+- `ops-events`: converge on run IDs, event names, statuses/severity, target identifiers, metadata/error normalization, and best-effort writes.
+
+## Project Movement
+
+- Relin should keep using Kysely for PG and replace its local connection lifecycle with `@q32/core/pg-kysely`.
+- DirtSignal should migrate new PG repositories to Kysely first, then wrap existing raw `postgres` repositories behind Kysely-compatible interfaces as they change.
+- Adgiro should adopt the shared D1 job driver shape and ops-event schema before adding PG. If it adds PG, it should start on Kysely rather than raw `postgres`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q32/core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
   "license": "MIT",
   "type": "module",
@@ -88,6 +88,10 @@
       "types": "./dist/pg.d.ts",
       "default": "./dist/pg.js"
     },
+    "./pg-kysely": {
+      "types": "./dist/pg-kysely.d.ts",
+      "default": "./dist/pg-kysely.js"
+    },
     "./r2-json": {
       "types": "./dist/r2-json.d.ts",
       "default": "./dist/r2-json.js"
@@ -115,6 +119,7 @@
   },
   "files": [
     "dist",
+    "src",
     "docs",
     "README.md",
     "LICENSE"
@@ -125,6 +130,11 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.15"
   },
+  "dependencies": {
+    "kysely": "^0.29.2",
+    "kysely-postgres-js": "^3.0.0",
+    "postgres": "^3.4.9"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/ai.ts

@@ -0,0 +1,42 @@
+export type AiMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+};
+
+export type AiJsonRequest = {
+  model: string;
+  messages: AiMessage[];
+  responseName?: string;
+  temperature?: number;
+};
+
+export type AiJsonProvider = {
+  generateJson<T>(request: AiJsonRequest): Promise<T>;
+};
+
+export type AiUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+};
+
+export type AiResult<T> = {
+  value: T;
+  usage?: AiUsage;
+  providerMetadata?: Record<string, unknown>;
+};
+
+export function systemUserMessages(system: string, user: string): AiMessage[] {
+  return [
+    { role: "system", content: system },
+    { role: "user", content: user },
+  ];
+}
+
+export function extractJsonObject(text: string): unknown {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) return JSON.parse(trimmed);
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced) return JSON.parse(fenced[1].trim());
+  throw new Error("No JSON object found in model output.");
+}

package/src/api.ts

@@ -0,0 +1,100 @@
+import { HttpError } from "./http.js";
+
+export type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface SchemaLike<T = unknown> {
+  parse(value: unknown): T;
+}
+
+export type ApiOperationSpec<TInput = unknown> = {
+  name: string;
+  title: string;
+  description: string;
+  method: ApiMethod;
+  path: string;
+  scope?: string;
+  inputSchema?: SchemaLike<TInput>;
+  openapi?: boolean;
+};
+
+export type ApiOperation<TContext, TInput = unknown, TOutput = unknown> = ApiOperationSpec<TInput> & {
+  handler: (context: TContext, input: TInput) => Promise<TOutput> | TOutput;
+};
+
+export type ApiOperationRegistry<TContext> = Record<string, ApiOperation<TContext, unknown, unknown>>;
+
+export function defineApiOperation<TContext, TInput = unknown, TOutput = unknown>(
+  operation: ApiOperation<TContext, TInput, TOutput>,
+): ApiOperation<TContext, TInput, TOutput> {
+  return operation;
+}
+
+export function defineApiRegistry<TContext, TRegistry extends ApiOperationRegistry<TContext>>(
+  registry: TRegistry,
+): TRegistry {
+  const names = new Set<string>();
+  for (const [key, operation] of Object.entries(registry)) {
+    if (operation.name !== key) throw new Error(`API operation key/name mismatch: ${key} != ${operation.name}`);
+    if (names.has(operation.name)) throw new Error(`Duplicate API operation name: ${operation.name}`);
+    names.add(operation.name);
+  }
+  return registry;
+}
+
+export async function dispatchApiOperation<TContext>(
+  registry: ApiOperationRegistry<TContext>,
+  name: string,
+  context: TContext,
+  input: unknown,
+): Promise<unknown> {
+  const operation = registry[name];
+  if (!operation) throw new HttpError(404, `Unknown API operation: ${name}`, "unknown_operation");
+  const parsed = operation.inputSchema ? operation.inputSchema.parse(input) : input;
+  return operation.handler(context, parsed);
+}
+
+export function operationPathParameters(path: string): string[] {
+  const params = new Set<string>();
+  for (const match of path.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) params.add(match[1]);
+  return [...params];
+}
+
+export function interpolateOperationPath(path: string, input: Record<string, unknown>): string {
+  return path.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key: string) => {
+    const value = input[key];
+    if (value === undefined || value === null || value === "") {
+      throw new HttpError(400, `Missing path parameter: ${key}`, "missing_path_parameter");
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+
+export function openApiPathsForRegistry<TContext>(
+  registry: ApiOperationRegistry<TContext>,
+): Record<string, Record<string, Record<string, unknown>>> {
+  const paths: Record<string, Record<string, Record<string, unknown>>> = {};
+  for (const operation of Object.values(registry)) {
+    if (operation.openapi === false) continue;
+    const path = operation.path.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, "{$1}");
+    const method = operation.method.toLowerCase();
+    paths[path] ??= {};
+    paths[path][method] = {
+      operationId: operation.name,
+      summary: operation.title,
+      description: operation.description,
+      security: operation.scope ? [{ bearerAuth: [operation.scope] }] : undefined,
+      parameters: operationPathParameters(operation.path).map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      })),
+      responses: {
+        "200": {
+          description: "OK",
+        },
+      },
+    };
+  }
+  return paths;
+}

package/src/billing.ts

@@ -0,0 +1,46 @@
+export type BillingPlan = {
+  id: string;
+  name: string;
+  rank: number;
+  stripePriceId?: string;
+  limits?: Record<string, number>;
+};
+
+export type SubscriptionStatus =
+  | "trialing"
+  | "active"
+  | "past_due"
+  | "canceled"
+  | "unpaid"
+  | "incomplete"
+  | "incomplete_expired"
+  | "paused";
+
+export type BillingCustomer = {
+  customerId: string;
+  email?: string;
+  planId?: string;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+  subscriptionStatus?: SubscriptionStatus;
+};
+
+export function planAtLeast(plans: BillingPlan[], actualPlanId: string | null | undefined, requiredPlanId: string): boolean {
+  const byId = new Map(plans.map((plan) => [plan.id, plan]));
+  const actual = actualPlanId ? byId.get(actualPlanId) : undefined;
+  const required = byId.get(requiredPlanId);
+  if (!actual || !required) return false;
+  return actual.rank >= required.rank;
+}
+
+export function activeSubscriptionStatuses(): SubscriptionStatus[] {
+  return ["trialing", "active"];
+}
+
+export function isActiveSubscriptionStatus(status: SubscriptionStatus | null | undefined): boolean {
+  return status === "trialing" || status === "active";
+}
+
+export function stripeEventAlreadyProcessedMessage(eventId: string): string {
+  return `Stripe event already processed: ${eventId}`;
+}

package/src/cloudflare.ts

@@ -0,0 +1,36 @@
+export type WorkerQueueMessage<T = unknown> = {
+  jobId: string;
+  payload?: T;
+};
+
+export type DurableObjectIdLike = {
+  toString(): string;
+};
+
+export function requireD1(env: Record<string, unknown>, binding = "DB"): D1Database {
+  const db = env[binding];
+  if (!db || typeof db !== "object" || typeof (db as D1Database).prepare !== "function") {
+    throw new Error(`Missing D1 binding: ${binding}`);
+  }
+  return db as D1Database;
+}
+
+export function requireR2(env: Record<string, unknown>, binding: string): R2Bucket {
+  const bucket = env[binding];
+  if (!bucket || typeof bucket !== "object" || typeof (bucket as R2Bucket).put !== "function") {
+    throw new Error(`Missing R2 binding: ${binding}`);
+  }
+  return bucket as R2Bucket;
+}
+
+export function requireQueue<T = unknown>(env: Record<string, unknown>, binding: string): Queue<T> {
+  const queue = env[binding];
+  if (!queue || typeof queue !== "object" || typeof (queue as Queue<T>).send !== "function") {
+    throw new Error(`Missing Queue binding: ${binding}`);
+  }
+  return queue as Queue<T>;
+}
+
+export function isCloudflareScheduledEvent(value: unknown): value is ScheduledEvent {
+  return Boolean(value && typeof value === "object" && "scheduledTime" in value && "cron" in value);
+}

package/src/crypto.ts

@@ -0,0 +1,56 @@
+import { fromBase64Url, randomBase64Url, toBase64Url } from "./ids.js";
+
+const AES_GCM_IV_BYTES = 12;
+const AES_GCM_KEY_BYTES = 32;
+
+export type EncryptedJsonEnvelope = {
+  v: 1;
+  alg: "A256GCM";
+  iv: string;
+  ciphertext: string;
+};
+
+export function createEncryptionKey(): string {
+  return randomBase64Url(AES_GCM_KEY_BYTES);
+}
+
+export async function encryptJson(value: unknown, keyMaterial: string): Promise<EncryptedJsonEnvelope> {
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+  const key = await importAesKey(keyMaterial);
+  const plaintext = new TextEncoder().encode(JSON.stringify(value));
+  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, plaintext);
+  return {
+    v: 1,
+    alg: "A256GCM",
+    iv: toBase64Url(iv),
+    ciphertext: toBase64Url(new Uint8Array(ciphertext)),
+  };
+}
+
+export async function decryptJson<T>(envelope: EncryptedJsonEnvelope, keyMaterial: string): Promise<T> {
+  if (envelope.v !== 1 || envelope.alg !== "A256GCM") throw new Error("Unsupported encrypted JSON envelope.");
+  const key = await importAesKey(keyMaterial);
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(fromBase64Url(envelope.iv)) },
+    key,
+    toArrayBuffer(fromBase64Url(envelope.ciphertext)),
+  );
+  return JSON.parse(new TextDecoder().decode(plaintext)) as T;
+}
+
+async function importAesKey(keyMaterial: string): Promise<CryptoKey> {
+  let raw: Uint8Array;
+  try {
+    raw = fromBase64Url(keyMaterial);
+  } catch {
+    throw new Error("Encryption key must be 32 base64url-encoded bytes.");
+  }
+  if (raw.byteLength !== AES_GCM_KEY_BYTES) {
+    throw new Error("Encryption key must be 32 base64url-encoded bytes.");
+  }
+  return crypto.subtle.importKey("raw", toArrayBuffer(raw), "AES-GCM", false, ["encrypt", "decrypt"]);
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}

package/src/d1.ts

@@ -0,0 +1,86 @@
+export type D1Primitive = string | number | boolean | null | Uint8Array;
+
+export interface D1StatementResult {
+  success: boolean;
+  meta: Record<string, unknown>;
+  results?: Record<string, unknown>[];
+}
+
+export interface D1PreparedStatementLike {
+  bind(...values: D1Primitive[]): D1PreparedStatementLike;
+  run(): Promise<D1StatementResult>;
+  first<T extends object = Record<string, unknown>>(): Promise<T | null>;
+  all<T extends object = Record<string, unknown>>(): Promise<{ results: T[] }>;
+}
+
+export interface D1DatabaseLike {
+  prepare(query: string): D1PreparedStatementLike;
+  batch(statements: D1PreparedStatementLike[]): Promise<D1StatementResult[]>;
+  exec(query: string): Promise<unknown>;
+}
+
+export type Migration = {
+  id: string;
+  sql: string;
+};
+
+export type MigrationResult = {
+  applied: string[];
+  skipped: string[];
+};
+
+export async function ensureMigrationsTable(db: D1DatabaseLike, tableName = "schema_migrations"): Promise<void> {
+  assertSafeIdentifier(tableName);
+  await db.exec(
+    `CREATE TABLE IF NOT EXISTS ${tableName} (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+  );
+}
+
+export async function applyD1Migrations(
+  db: D1DatabaseLike,
+  migrations: Migration[],
+  options: { tableName?: string } = {},
+): Promise<MigrationResult> {
+  const tableName = options.tableName ?? "schema_migrations";
+  assertSafeIdentifier(tableName);
+  await ensureMigrationsTable(db, tableName);
+
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const migration of migrations) {
+    const existing = await db.prepare(`SELECT id FROM ${tableName} WHERE id = ? LIMIT 1`).bind(migration.id).first();
+    if (existing) {
+      skipped.push(migration.id);
+      continue;
+    }
+
+    await db.exec(migration.sql);
+    await db.prepare(`INSERT INTO ${tableName} (id) VALUES (?)`).bind(migration.id).run();
+    applied.push(migration.id);
+  }
+
+  return { applied, skipped };
+}
+
+export function parseJsonColumn<T>(value: string | null | undefined, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export function stringifyJsonColumn(value: unknown): string {
+  return JSON.stringify(value ?? null);
+}
+
+function assertSafeIdentifier(value: string): void {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`Unsafe SQL identifier: ${value}`);
+  }
+}