@flaredev/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muke Johnbaptist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @flaredev/core
+
+The runtime for [Flare](https://flare-docs.codetotech.com) apps: resource
+descriptors and the field grammar, the resource store and validators, policies,
+auth, mail and storage helpers, realtime (Durable Objects), billing rules and
+the security layer.
+
+Apps created with [`@flaredev/cli`](https://www.npmjs.com/package/@flaredev/cli)
+depend on this package already. You rarely add it by hand:
+
+```sh
+npm create flare-framework@latest my-app
+```
+
+Entry points: `@flaredev/core`, `/server`, `/client`, `/react`, `/realtime`,
+`/realtime/server`, `/security`, `/security/server`.
+
+Requires Node.js 22 or later.

package/dist/chunk-DARDHZPX.js

@@ -0,0 +1,192 @@
+// src/resource/naming.ts
+function words(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean).map((word) => word.toLowerCase());
+}
+var pascalCase = (value) => words(value).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+var camelCase = (value) => {
+  const pascal = pascalCase(value);
+  return pascal ? pascal[0].toLowerCase() + pascal.slice(1) : pascal;
+};
+var snakeCase = (value) => words(value).join("_");
+var kebabCase = (value) => words(value).join("-");
+var humanize = (value) => {
+  const text = words(value).join(" ");
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+};
+var UNCOUNTABLE = /* @__PURE__ */ new Set(["equipment", "information", "rice", "money", "species", "series", "fish", "sheep", "data", "news"]);
+var IRREGULAR = { person: "people", man: "men", woman: "women", child: "children", mouse: "mice" };
+function pluralize(value) {
+  const match = /([A-Za-z]+)$/.exec(value);
+  if (!match) return value;
+  const word = match[1];
+  const lower = word.toLowerCase();
+  const head = value.slice(0, value.length - word.length);
+  const keepCase = (plural) => word[0] === word[0].toUpperCase() ? plural[0].toUpperCase() + plural.slice(1) : plural;
+  if (UNCOUNTABLE.has(lower)) return value;
+  if (IRREGULAR[lower]) return head + keepCase(IRREGULAR[lower]);
+  if (/[^aeiou]y$/i.test(word)) return head + word.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/i.test(word)) return head + word + "es";
+  return head + word + "s";
+}
+
+// src/resource/define.ts
+var RESERVED_FIELD_NAMES = ["id", "createdAt", "updatedAt"];
+var ResourceDefinitionError = class extends Error {
+  constructor(resource, message) {
+    super(`Resource "${resource}": ${message}`);
+    this.name = "ResourceDefinitionError";
+  }
+};
+var IDENTIFIER = /^[a-z][A-Za-z0-9]*$/;
+function defaultFieldLabel(key, field) {
+  return humanize(field.kind === "belongsTo" ? key.replace(/Id$/, "") : key);
+}
+function defineResource(config) {
+  const name = config.name;
+  const fail = (message) => {
+    throw new ResourceDefinitionError(name, message);
+  };
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(name) || pascalCase(name) !== name) fail('name must be PascalCase, e.g. "OrderItem".');
+  const entries = Object.entries(config.fields);
+  if (entries.length === 0) fail("define at least one field.");
+  const fields = {};
+  for (const [key, def] of entries) {
+    if (!IDENTIFIER.test(key)) fail(`field "${key}" must be camelCase (letters and digits, starting lowercase).`);
+    if (RESERVED_FIELD_NAMES.includes(key)) fail(`"${key}" is added automatically; don't declare it.`);
+    if (def.kind === "enum") {
+      if (def.options.length === 0) fail(`enum field "${key}" needs at least one option.`);
+      if (new Set(def.options).size !== def.options.length) fail(`enum field "${key}" has duplicate options.`);
+      if (def.default !== void 0 && !def.options.includes(def.default)) fail(`default of "${key}" isn't one of its options.`);
+    }
+    if (def.kind === "belongsTo" && !key.endsWith("Id")) fail(`belongsTo field "${key}" must end in "Id", e.g. "${camelCase(def.target)}Id".`);
+    if ((def.kind === "belongsTo" || def.kind === "hasMany") && pascalCase(def.target) !== def.target) {
+      fail(`relation "${key}" must target a PascalCase resource name.`);
+    }
+    if (def.kind === "belongsTo" && def.onDelete === "set null" && def.required) {
+      fail(`"${key}" uses onDelete "set null" but is required; mark it required: false.`);
+    }
+    if (def.kind === "file" && def.accept.length === 0) fail(`file field "${key}" must accept at least one category.`);
+    fields[key] = { ...def, label: def.label ?? defaultFieldLabel(key, def) };
+  }
+  const stored = entries.filter(([, def]) => def.kind !== "hasMany");
+  const titleField = config.titleField ?? stored.find(([, def]) => def.kind === "string")?.[0] ?? stored[0]?.[0] ?? "id";
+  if (config.titleField && !stored.some(([key]) => key === config.titleField)) {
+    fail(`titleField "${config.titleField}" isn't a stored field.`);
+  }
+  const defaultSort = config.defaultSort ?? { field: "createdAt", direction: "desc" };
+  if (!["createdAt", "updatedAt"].includes(defaultSort.field) && !stored.some(([key]) => key === defaultSort.field)) {
+    fail(`defaultSort field "${defaultSort.field}" isn't a stored field.`);
+  }
+  const perPage = config.perPage ?? 25;
+  if (!Number.isInteger(perPage) || perPage < 1 || perPage > 100) fail("perPage must be an integer from 1 to 100.");
+  const pluralName = pluralize(name);
+  return {
+    name,
+    table: config.table ?? snakeCase(pluralName),
+    slug: config.slug ?? kebabCase(pluralName),
+    label: config.label ?? humanize(name),
+    pluralLabel: config.pluralLabel ?? humanize(pluralName),
+    icon: config.icon,
+    titleField,
+    defaultSort,
+    perPage,
+    fields,
+    $types: void 0
+  };
+}
+function storedFields(resource) {
+  return Object.entries(resource.fields).filter(([, def]) => def.kind !== "hasMany");
+}
+var columnName = (key) => snakeCase(key);
+
+// src/resource/validators.ts
+import { z } from "zod";
+var DEFAULT_STRING_MAX = 255;
+var DEFAULT_TEXT_MAX = 65535;
+var OBJECT_KEY = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).{1,1024}$/;
+var typeError = (message) => (issue) => issue.input === void 0 || issue.input === null || issue.input === "" ? "Required" : message;
+function stringSchema(max, min, required) {
+  let s = z.string({ error: typeError("Enter text") });
+  if (max) s = s.max(max, `At most ${max} characters`);
+  if (min !== void 0) s = s.min(min, min === 1 ? "Required" : `At least ${min} characters`);
+  else if (required) s = s.min(1, "Required");
+  return s;
+}
+function fieldSchema(def) {
+  switch (def.kind) {
+    case "string": {
+      let s = z.string({ error: typeError("Enter text") }).trim().max(def.maxLength ?? DEFAULT_STRING_MAX, `At most ${def.maxLength ?? DEFAULT_STRING_MAX} characters`);
+      if (def.minLength !== void 0) s = s.min(def.minLength, `At least ${def.minLength} characters`);
+      else if (def.required) s = s.min(1, "Required");
+      if (def.pattern) s = s.regex(new RegExp(def.pattern), "Invalid format");
+      if (def.format === "email") return s.pipe(z.email({ error: "Enter a valid email address" }));
+      if (def.format === "url") return s.pipe(z.url({ protocol: /^https?$/, error: "Enter a valid URL (http or https)" }));
+      return s;
+    }
+    case "text":
+      return stringSchema(def.maxLength ?? DEFAULT_TEXT_MAX, def.minLength, def.required);
+    case "int":
+    case "float": {
+      let s = z.number({ error: typeError("Enter a number") });
+      if (def.kind === "int") s = s.int("Enter a whole number");
+      if (def.min !== void 0) s = s.min(def.min, `Must be at least ${def.min}`);
+      if (def.max !== void 0) s = s.max(def.max, `Must be at most ${def.max}`);
+      return s;
+    }
+    case "boolean":
+      return z.boolean({ error: typeError("Choose yes or no") });
+    case "date":
+      return z.iso.date({ error: typeError("Enter a valid date") });
+    case "datetime":
+      return z.iso.datetime({ offset: true, error: typeError("Enter a valid date and time") });
+    case "enum":
+      return z.enum(def.options, { error: typeError("Choose one of the options") });
+    case "file":
+      return z.string({ error: typeError("Upload a file") }).regex(OBJECT_KEY, "Invalid file");
+    case "belongsTo":
+      return z.string({ error: typeError("Choose a record") }).min(1, "Required");
+  }
+}
+var fileKeyPrefix = (resource, fieldKey) => `${resource.table}/${fieldKey}/`;
+function createValidators(resource) {
+  const create = {};
+  const update = {};
+  for (const [key, def] of storedFields(resource)) {
+    let base = fieldSchema(def);
+    if (def.kind === "file") {
+      const prefix = fileKeyPrefix(resource, key);
+      base = base.refine(
+        (value2) => typeof value2 !== "string" || !OBJECT_KEY.test(value2) || value2.startsWith(prefix),
+        "This file wasn't uploaded for this field"
+      );
+    }
+    const value = def.required ? base : base.nullable();
+    update[key] = value.optional();
+    const hasDefault = "default" in def && def.default !== void 0;
+    create[key] = def.required && !hasDefault ? value : value.optional();
+  }
+  const unknownKeys = { error: (issue) => issue.code === "unrecognized_keys" ? `Unknown field(s): ${issue.keys?.join(", ")}` : void 0 };
+  return {
+    create: z.strictObject(create, unknownKeys),
+    update: z.strictObject(update, unknownKeys)
+  };
+}
+
+export {
+  words,
+  pascalCase,
+  camelCase,
+  snakeCase,
+  kebabCase,
+  humanize,
+  pluralize,
+  RESERVED_FIELD_NAMES,
+  ResourceDefinitionError,
+  defaultFieldLabel,
+  defineResource,
+  storedFields,
+  columnName,
+  fieldSchema,
+  fileKeyPrefix,
+  createValidators
+};

package/dist/chunk-KSVLQLJD.js

@@ -0,0 +1,91 @@
+// src/security/config.ts
+var NAME = /^[a-z][a-z0-9-]{1,47}$/;
+function defineSecurity(config) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const detector of config.detectors ?? []) {
+    if (!NAME.test(detector.name)) throw new Error(`Detector name "${detector.name}" must be lowercase letters, digits and dashes.`);
+    if (seen.has(detector.name)) throw new Error(`Detector "${detector.name}" is defined twice.`);
+    seen.add(detector.name);
+    if (!(detector.threshold >= 1) || !(detector.windowSeconds >= 1)) {
+      throw new Error(`Detector "${detector.name}" needs a threshold and windowSeconds of at least 1.`);
+    }
+    if (detector.ban && !(detector.ban.seconds >= 60)) throw new Error(`Detector "${detector.name}" must ban for at least 60 seconds.`);
+  }
+  for (const rule of [...config.zone?.rateLimits ?? [], ...config.zone?.customRules ?? []]) {
+    if (!NAME.test(rule.name)) throw new Error(`Zone rule name "${rule.name}" must be lowercase letters, digits and dashes.`);
+    if (!rule.expression.trim()) throw new Error(`Zone rule "${rule.name}" needs an expression.`);
+  }
+  for (const ip of config.allow ?? []) {
+    if (!isIp(ip)) throw new Error(`allow: "${ip}" is not an IP address.`);
+  }
+  return config;
+}
+function detectorMatches(detector, request, status) {
+  const { method, path, status: statuses } = detector.match;
+  if (method && method.toUpperCase() !== request.method.toUpperCase()) return false;
+  const pathname = new URL(request.url).pathname;
+  if (typeof path === "string" ? pathname !== path : !path.test(pathname)) return false;
+  if (statuses === void 0) return true;
+  return (Array.isArray(statuses) ? statuses : [statuses]).includes(status);
+}
+function recordHit(previous, now, windowSeconds, threshold) {
+  const since = now - windowSeconds * 1e3;
+  const hits = [...previous.filter((at) => at > since), now];
+  return { hits, tripped: hits.length === threshold };
+}
+function clientIp(request) {
+  const ip = request.headers.get("cf-connecting-ip")?.trim();
+  return ip && isIp(ip) ? ip : null;
+}
+var IPV4 = /^(25[0-5]|2[0-4]\d|1?\d?\d)(\.(25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+function isIp(value) {
+  if (IPV4.test(value)) return true;
+  if (!/^[0-9a-f:.]+$/i.test(value) || !value.includes(":")) return false;
+  try {
+    new URL(`http://[${value}]/`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var zoneRuleTag = (app, name) => `flare:${app}:${name}`;
+var isFlareRule = (app, description) => Boolean(description?.startsWith(`flare:${app}:`));
+var DEFAULT_DETECTORS = [
+  {
+    name: "login-brute-force",
+    description: "Repeated failed sign-ins from one IP",
+    match: { method: "POST", path: "/api/auth/sign-in/email", status: [401, 403] },
+    threshold: 5,
+    windowSeconds: 60,
+    ban: { seconds: 60 * 60 },
+    severity: "high"
+  },
+  {
+    name: "checkout-abuse",
+    description: "Many checkout attempts from one IP",
+    match: { method: "POST", path: /^\/api\/billing\/checkout$/ },
+    threshold: 10,
+    windowSeconds: 60,
+    ban: { seconds: 30 * 60 },
+    severity: "medium"
+  },
+  {
+    name: "api-scraping",
+    description: "Rapid reads across the REST API from one IP",
+    match: { method: "GET", path: /^\/api\/(?!auth\/|health$)/ },
+    threshold: 300,
+    windowSeconds: 60,
+    severity: "low"
+  }
+];
+
+export {
+  defineSecurity,
+  detectorMatches,
+  recordHit,
+  clientIp,
+  isIp,
+  zoneRuleTag,
+  isFlareRule,
+  DEFAULT_DETECTORS
+};

package/dist/chunk-LYQT4S47.js

@@ -0,0 +1,248 @@
+import {
+  DEFAULT_RECONNECT_POLICY
+} from "./chunk-ZJPJGME5.js";
+
+// src/realtime/client.ts
+var SERVICE_RESTART = 1012;
+function subscribe(set, handler) {
+  set.add(handler);
+  return () => {
+    set.delete(handler);
+  };
+}
+var RealtimeClient = class {
+  channel;
+  members = [];
+  status = "connecting";
+  /** This connection's id, from the server's `hello` (new on every reconnect). */
+  connectionId = null;
+  url;
+  policy;
+  presence;
+  ws = null;
+  attempt = 0;
+  explicitClose = false;
+  reconnectTimer = null;
+  deadTimer = null;
+  stableTimer = null;
+  heartbeatInterval = null;
+  lastPongAt = 0;
+  listeners = /* @__PURE__ */ new Map();
+  anyHandlers = /* @__PURE__ */ new Set();
+  memberHandlers = /* @__PURE__ */ new Set();
+  statusHandlers = /* @__PURE__ */ new Set();
+  /**
+   * @param channel Channel name to join, e.g. `"deals"`.
+   * @param opts.path Websocket endpoint (default `/realtime`); the URL is
+   *          resolved against `location` in the browser, or the given
+   *          `baseUrl`. Scheme is upgraded to `wss:` / `ws:` automatically.
+   */
+  constructor(channel, opts = {}) {
+    this.channel = channel;
+    this.policy = { ...DEFAULT_RECONNECT_POLICY, ...opts.reconnect };
+    this.presence = opts.presence ?? null;
+    const path = opts.path ?? "/realtime";
+    const base = opts.baseUrl ?? (typeof location !== "undefined" ? location.href : "http://localhost:8787/");
+    const url = new URL(base);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = `${path.replace(/\/$/, "")}/${channel}/ws`;
+    url.search = "";
+    url.hash = "";
+    this.url = url.toString();
+  }
+  /** Subscribe to one application event type. Returns an unsubscribe fn. */
+  on(e, handler) {
+    let set = this.listeners.get(e);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(e, set);
+    }
+    return subscribe(set, handler);
+  }
+  /** Subscribe to every application event on the channel. */
+  onAny(handler) {
+    return subscribe(this.anyHandlers, handler);
+  }
+  /** Presence change notifications (full member list on every change). */
+  onMembers(handler) {
+    return subscribe(this.memberHandlers, handler);
+  }
+  onStatus(handler) {
+    return subscribe(this.statusHandlers, handler);
+  }
+  /** Set presence for this connection; sends a `join` frame if already connected. */
+  setPresence(presence) {
+    this.presence = presence;
+    if (this.connected()) this.send({ t: "join", presence });
+  }
+  /** Broadcast an application event to every other member (needs a `send` grant). */
+  publish(e, d) {
+    return this.send({ t: "send", e, d });
+  }
+  connected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+  /** Connect and join; no-op if already connected or connecting. Resumes after close(). */
+  connect() {
+    if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+      return this;
+    }
+    this.explicitClose = false;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    this.setStatus(this.attempt > 0 ? "reconnecting" : "connecting");
+    let ws;
+    try {
+      ws = new WebSocket(this.url);
+    } catch {
+      this.setStatus("dead");
+      return this;
+    }
+    this.ws = ws;
+    ws.addEventListener("open", () => ws === this.ws && this.handleOpen());
+    ws.addEventListener("message", (event) => ws === this.ws && this.handleMessage(String(event.data)));
+    ws.addEventListener("close", (event) => ws === this.ws && this.handleClose(event));
+    return this;
+  }
+  /** Close and stop reconnecting and keepalive, until connect() is called again. */
+  close() {
+    this.explicitClose = true;
+    this.clearTimers();
+    this.setStatus("closed");
+    const ws = this.ws;
+    this.ws = null;
+    if (ws) {
+      try {
+        ws.close(1e3, "Client closed");
+      } catch {
+      }
+    }
+  }
+  send(frame) {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    try {
+      ws.send(JSON.stringify(frame));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  handleOpen() {
+    if (this.deadTimer) clearTimeout(this.deadTimer);
+    this.deadTimer = null;
+    this.stableTimer = setTimeout(() => {
+      this.attempt = 0;
+      this.stableTimer = null;
+    }, this.policy.stableMs);
+    this.send({ t: "join", presence: this.presence });
+    this.startHeartbeat();
+    this.setStatus("open");
+  }
+  handleMessage(raw) {
+    let frame;
+    try {
+      frame = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    switch (frame.t) {
+      case "hello":
+        this.connectionId = frame.connectionId;
+        this.setMembers(frame.members);
+        break;
+      case "presence":
+        this.setMembers(frame.members);
+        break;
+      case "event":
+        this.dispatch(frame.e, frame.d, frame.from);
+        break;
+      case "pong":
+        this.lastPongAt = Date.now();
+        break;
+      case "error":
+        break;
+    }
+  }
+  setMembers(members) {
+    this.members = members;
+    for (const handler of [...this.memberHandlers]) handler(members);
+  }
+  dispatch(e, d, from) {
+    for (const handler of [...this.anyHandlers]) handler(e, d, from);
+    const set = this.listeners.get(e);
+    if (!set) return;
+    for (const handler of [...set]) handler(d, from);
+  }
+  handleClose(event) {
+    this.ws = null;
+    this.clearHeartbeat();
+    if (this.stableTimer) clearTimeout(this.stableTimer);
+    this.stableTimer = null;
+    if (this.explicitClose) return;
+    if (event.code === SERVICE_RESTART) this.attempt = 0;
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    if (this.policy.maxRetries > 0 && this.attempt >= this.policy.maxRetries) {
+      this.setStatus("dead");
+      return;
+    }
+    this.setStatus("reconnecting");
+    if (!this.deadTimer && this.policy.deadAfterMs > 0) {
+      this.deadTimer = setTimeout(() => {
+        this.deadTimer = null;
+        if (this.status === "reconnecting") this.setStatus("dead");
+      }, this.policy.deadAfterMs);
+    }
+    const delay = this.nextDelay();
+    this.attempt += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+  /** Exponential backoff with jitter, never above maxDelayMs. */
+  nextDelay() {
+    const base = this.policy.minDelayMs * Math.pow(this.policy.factor, Math.min(this.attempt, 16));
+    const jitter = this.policy.jitterRatio > 0 ? (Math.random() * 2 - 1) * this.policy.jitterRatio : 0;
+    return Math.max(0, Math.round(Math.min(base * (1 + jitter), this.policy.maxDelayMs)));
+  }
+  startHeartbeat() {
+    this.clearHeartbeat();
+    const interval = this.policy.heartbeatMs;
+    if (interval <= 0) return;
+    this.lastPongAt = Date.now();
+    this.heartbeatInterval = setInterval(() => {
+      if (!this.connected()) return;
+      if (Date.now() - this.lastPongAt >= interval * 2) {
+        try {
+          this.ws?.close(4e3, "Heartbeat timeout");
+        } catch {
+        }
+        return;
+      }
+      this.send({ t: "ping" });
+    }, interval);
+  }
+  clearTimers() {
+    for (const timer of [this.reconnectTimer, this.deadTimer, this.stableTimer]) if (timer) clearTimeout(timer);
+    this.reconnectTimer = null;
+    this.deadTimer = null;
+    this.stableTimer = null;
+    this.clearHeartbeat();
+  }
+  clearHeartbeat() {
+    if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+    this.heartbeatInterval = null;
+  }
+  setStatus(status) {
+    if (this.status === status) return;
+    this.status = status;
+    for (const handler of [...this.statusHandlers]) handler(status);
+  }
+};
+
+export {
+  RealtimeClient
+};

package/dist/chunk-ZJPJGME5.js

@@ -0,0 +1,40 @@
+// src/realtime/types.ts
+var DEFAULT_RECONNECT_POLICY = {
+  minDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  factor: 2,
+  jitterRatio: 0.2,
+  maxRetries: 0,
+  deadAfterMs: 12e4,
+  heartbeatMs: 3e4,
+  stableMs: 1e4
+};
+function parseClientFrame(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "Not valid JSON." };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { ok: false, reason: "Frame must be an object." };
+  const frame = parsed;
+  if (frame.t === "join") {
+    if (frame.presence !== void 0 && (typeof frame.presence !== "object" || frame.presence === null)) {
+      return { ok: false, reason: "presence must be an object." };
+    }
+    return { ok: true, frame: { t: "join", presence: frame.presence } };
+  }
+  if (frame.t === "ping") return { ok: true, frame: { t: "ping" } };
+  if (frame.t === "send") {
+    if (typeof frame.e !== "string" || frame.e.length === 0 || frame.e.length > 128) {
+      return { ok: false, reason: "send.e must be a string of up to 128 characters." };
+    }
+    return { ok: true, frame: { t: "send", e: frame.e, d: frame.d } };
+  }
+  return { ok: false, reason: `Unknown frame type "${String(frame.t)}".` };
+}
+
+export {
+  DEFAULT_RECONNECT_POLICY,
+  parseClientFrame
+};

package/dist/client.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed client for a generated resource's REST API. Browser- and server-safe: no
+ * zod or drizzle imports, types come from the descriptor via `import type`.
+ *
+ *   import type contact from "@/resources/contact.resource";
+ *   const contacts = createResourceClient<typeof contact>("/api/contacts");
+ *   const { data, meta } = await contacts.list({ q: "ada", sort: "-createdAt" });
+ */
+interface ResourceTypes {
+    $types: {
+        create: object;
+        update: object;
+        record: object;
+    };
+}
+interface ListParams {
+    page?: number;
+    perPage?: number;
+    /** Field key, prefixed with "-" for descending. */
+    sort?: string;
+    q?: string;
+    filter?: Record<string, string | number | boolean | null>;
+}
+interface ListResult<T> {
+    data: T[];
+    meta: {
+        page: number;
+        perPage: number;
+        total: number;
+        totalPages: number;
+    };
+}
+interface ApiIssue {
+    path?: string;
+    param?: string;
+    message: string;
+}
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly issues: ApiIssue[];
+    readonly field?: string;
+    constructor(status: number, body: {
+        error?: string;
+        issues?: ApiIssue[];
+        field?: string;
+    } | null);
+}
+interface ClientOptions {
+    /** Origin for server-side use, e.g. "https://example.com". Default: relative URLs. */
+    baseURL?: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+declare function createResourceClient<R extends ResourceTypes>(path: string, options?: ClientOptions): {
+    list(params?: ListParams): Promise<ListResult<R["$types"]["record"]>>;
+    get: (id: string) => Promise<R["$types"]["record"]>;
+    create: (input: R["$types"]["create"]) => Promise<R["$types"]["record"]>;
+    /** Partial update (PATCH). */
+    update: (id: string, input: R["$types"]["update"]) => Promise<R["$types"]["record"]>;
+    /** Full replacement (PUT): omitted optional fields are cleared. */
+    replace: (id: string, input: R["$types"]["create"]) => Promise<R["$types"]["record"]>;
+    delete: (id: string) => Promise<void>;
+};
+type ResourceClient<R extends ResourceTypes> = ReturnType<typeof createResourceClient<R>>;
+
+export { ApiError, type ApiIssue, type ClientOptions, type ListParams, type ListResult, type ResourceClient, type ResourceTypes, createResourceClient };