@q32/core 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q32/core",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Shared TypeScript primitives for Q32 Cloudflare Worker projects.",
   "license": "MIT",
   "type": "module",
@@ -115,6 +115,7 @@
   },
   "files": [
     "dist",
+    "src",
     "docs",
     "README.md",
     "LICENSE"

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}`);
+  }
+}

package/src/email.ts

@@ -0,0 +1,49 @@
+export type EmailAddress = {
+  email: string;
+  name?: string;
+};
+
+export type EmailAttachment = {
+  filename: string;
+  contentType: string;
+  data: Uint8Array | string;
+};
+
+export type SendEmailInput = {
+  from: EmailAddress;
+  to: EmailAddress[];
+  cc?: EmailAddress[];
+  bcc?: EmailAddress[];
+  replyTo?: EmailAddress[];
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: EmailAttachment[];
+  tags?: Record<string, string>;
+};
+
+export type SendEmailResult = {
+  id: string;
+  provider?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export interface EmailProvider {
+  send(input: SendEmailInput): Promise<SendEmailResult>;
+}
+
+export function formatEmailAddress(address: EmailAddress): string {
+  if (!address.name) return address.email;
+  const escaped = address.name.replace(/"/g, '\\"');
+  return `"${escaped}" <${address.email}>`;
+}
+
+export function normalizeEmailAddress(email: string): string {
+  const normalized = email.trim().toLowerCase();
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(normalized)) throw new Error(`Invalid email address: ${email}`);
+  return normalized;
+}
+
+export function appendUnsubscribeFooter(text: string, unsubscribeUrl: string): string {
+  return `${text.trim()}\n\nUnsubscribe: ${unsubscribeUrl}\n`;
+}

package/src/encoding.ts

@@ -0,0 +1,17 @@
+export function base64ToArrayBuffer(value: string): ArrayBuffer {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes.buffer;
+}
+
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    binary += String.fromCharCode(bytes[index]);
+  }
+  return btoa(binary);
+}

package/src/env.ts

@@ -0,0 +1,63 @@
+export type EnvSource = Record<string, unknown>;
+
+export class EnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EnvError";
+  }
+}
+
+export function requiredString(env: EnvSource, key: string): string {
+  const value = env[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new EnvError(`Missing required env var: ${key}`);
+  }
+  return value;
+}
+
+export function optionalString(env: EnvSource, key: string, fallback?: string): string | undefined {
+  const value = env[key];
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value !== "string") throw new EnvError(`Expected ${key} to be a string.`);
+  return value;
+}
+
+export function requiredUrl(env: EnvSource, key: string): string {
+  const value = requiredString(env, key);
+  try {
+    return new URL(value).toString().replace(/\/$/, "");
+  } catch {
+    throw new EnvError(`Expected ${key} to be a valid URL.`);
+  }
+}
+
+export function optionalBoolean(env: EnvSource, key: string, fallback = false): boolean {
+  const value = env[key];
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") throw new EnvError(`Expected ${key} to be boolean-like.`);
+  if (/^(1|true|yes|on)$/i.test(value)) return true;
+  if (/^(0|false|no|off)$/i.test(value)) return false;
+  throw new EnvError(`Expected ${key} to be boolean-like.`);
+}
+
+export function requiredBinding<T>(env: EnvSource, key: string): T {
+  const value = env[key];
+  if (value === undefined || value === null) throw new EnvError(`Missing required binding: ${key}`);
+  return value as T;
+}
+
+export type AppUrlOptions = {
+  fallback?: string;
+  keys?: string[];
+};
+
+export function appUrl(
+  env: EnvSource,
+  fallbackOrOptions: string | AppUrlOptions = "http://localhost:8787",
+): string {
+  const options = typeof fallbackOrOptions === "string" ? { fallback: fallbackOrOptions } : fallbackOrOptions;
+  const keys = options.keys ?? ["APP_URL", "BASE_URL", "PUBLIC_APP_URL"];
+  const value = keys.map((key) => optionalString(env, key)).find((candidate) => candidate !== undefined) ?? options.fallback ?? "http://localhost:8787";
+  return value.replace(/\/$/, "");
+}

package/src/hash.ts

@@ -0,0 +1,57 @@
+const encoder = new TextEncoder();
+
+export function toHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export async function sha256Hex(value: string | ArrayBuffer): Promise<string> {
+  const data = typeof value === "string" ? encoder.encode(value) : value;
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return toHex(new Uint8Array(digest));
+}
+
+export async function hmacSha256Hex(
+  secret: string,
+  value: string | ArrayBuffer,
+): Promise<string> {
+  const signature = await hmacSha256(secret, value);
+  return toHex(new Uint8Array(signature));
+}
+
+export async function hmacSha256Base64(
+  secret: string,
+  value: string | ArrayBuffer,
+): Promise<string> {
+  const signature = await hmacSha256(secret, value);
+  return toBase64(new Uint8Array(signature));
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let mismatch = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    mismatch |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return mismatch === 0;
+}
+
+async function hmacSha256(
+  secret: string,
+  value: string | ArrayBuffer,
+): Promise<ArrayBuffer> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const data = typeof value === "string" ? encoder.encode(value) : value;
+  return crypto.subtle.sign("HMAC", key, data);
+}

package/src/http.ts

@@ -0,0 +1,78 @@
+export type JsonResponseInit = ResponseInit & {
+  pretty?: boolean;
+};
+
+export type FetchLike = typeof fetch;
+
+export const defaultFetch: FetchLike = (input, init) => fetch(input, init);
+
+export class HttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code = "http_error",
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+export function jsonResponse(value: unknown, init: JsonResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has("content-type")) headers.set("content-type", "application/json; charset=utf-8");
+  return new Response(JSON.stringify(value, null, init.pretty ? 2 : 0), {
+    ...init,
+    headers,
+  });
+}
+
+export function errorResponse(error: unknown, fallbackStatus = 500): Response {
+  if (error instanceof HttpError) {
+    return jsonResponse({ error: { code: error.code, message: error.message } }, { status: error.status });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return jsonResponse({ error: { code: "internal_error", message } }, { status: fallbackStatus });
+}
+
+export async function readJson<T = unknown>(request: Request): Promise<T> {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) {
+    throw new HttpError(415, "Expected application/json request body.", "unsupported_media_type");
+  }
+  try {
+    return (await request.json()) as T;
+  } catch {
+    throw new HttpError(400, "Invalid JSON request body.", "invalid_json");
+  }
+}
+
+export function requireBearerToken(request: Request): string {
+  const value = request.headers.get("authorization") ?? "";
+  const match = value.match(/^Bearer\s+(.+)$/i);
+  if (!match) throw new HttpError(401, "Missing bearer token.", "missing_bearer_token");
+  return match[1];
+}
+
+export function requireAdminToken(request: Request, expected: string | undefined): void {
+  if (!expected) throw new HttpError(500, "Admin token is not configured.", "admin_token_not_configured");
+  const provided = request.headers.get("x-admin-token") ?? requireBearerToken(request);
+  if (provided !== expected) throw new HttpError(403, "Invalid admin token.", "invalid_admin_token");
+}
+
+export function absoluteUrl(appUrl: string, path: string): string {
+  return `${appUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+}
+
+export function escapeHtml(value: string | null | undefined): string {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+export async function readResponseExcerpt(response: Response, maxLength = 800): Promise<string> {
+  const text = await response.text().catch(() => "");
+  return text.slice(0, maxLength);
+}