@pylonsync/sdk 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -74,6 +74,14 @@ export interface FieldDefinition {
      * `serverOnly`, which hides a field from ALL client surfaces.
      */
     syncOmit?: boolean;
+    /**
+     * Longest value the field accepts, in characters (Unicode code
+     * points). Set with `field.string().max(n)` or
+     * `field.richtext().max(n)`. The server rejects a longer value with
+     * `FIELD_TOO_LONG` on every write path: the entity API, sync push,
+     * `ctx.db` in functions, and collaborative (CRDT) edits.
+     */
+    maxLength?: number;
     /**
      * When true, the field is **set on insert but cannot be changed
      * by client updates**. The framework rejects any `PATCH`/`PUT`
@@ -162,6 +170,15 @@ interface FieldBuilder {
      * editor still gets it via `db.get("Variant", id)`.
      */
     syncOmit(): FieldBuilder;
+    /**
+     * Cap the value at `n` characters (Unicode code points). String and
+     * richtext fields only. See [`FieldDefinition.maxLength`].
+     *
+     * Example: `bio: field.string().max(280)` stops any client, guests
+     * included, from storing a longer bio that every other client would
+     * then sync.
+     */
+    max(n: number): FieldBuilder;
     /**
      * Mark the field as set-on-insert-only. See [`FieldDefinition.readonly`]
      * for the full semantics.
@@ -334,6 +351,18 @@ export interface EntityDefinition {
      * can read" and "nothing".
      */
     sync?: boolean | SyncScope;
+    /**
+     * Record every insert, update, and delete in the audit log: actor,
+     * tenant, row id, and the names of changed fields (not their values).
+     * Read it with `ctx.audit.list({ entity })` or `GET /api/admin/audit`.
+     */
+    audit?: boolean;
+    /**
+     * Delete rows once they pass a retention period. A system job runs
+     * hourly; each deletion goes through the entity pipeline and is recorded
+     * in the audit log as `retention.delete`. See {@link RetentionRule}.
+     */
+    retention?: RetentionRule;
     /**
      * Per-row CRDT (Loro) documents. Default `true`: every write merges through
      * a document, and offline edits from several devices converge. Set `false`
@@ -376,6 +405,24 @@ export interface SyncScope {
      */
     limit?: number;
 }
+/**
+ * Retention rule for an entity.
+ *
+ * - `{ field: "createdAt", after: "365d" }` deletes a row once `createdAt`
+ *   is older than 365 days. Durations: `s`, `m`, `h`, `d`, `w`, `y`.
+ * - `{ field: "deleteAfter" }` (no `after`) deletes a row once
+ *   `deleteAfter` is in the past. Use it for a retention period per tenant:
+ *   set `deleteAfter` on each row at insert.
+ *
+ * `field` is a `datetime` field, or an `int`/`float` field holding unix
+ * milliseconds. Rows whose `hold` field (a `bool`) is true are kept, for
+ * example under a legal hold.
+ */
+export interface RetentionRule {
+    field: string;
+    after?: string;
+    hold?: string;
+}
 export declare function entity(name: string, fields: Record<string, FieldBuilder>, options?: {
     indexes?: IndexDefinition[];
     relations?: RelationDefinition[];
@@ -387,6 +434,12 @@ export declare function entity(name: string, fields: Record<string, FieldBuilder
     /** `false` for server-written rows that need no CRDT document. Mirrors
      *  {@link EntityDefinition.crdt}. */
     crdt?: boolean;
+    /** Record every write in the audit log. Mirrors
+     *  {@link EntityDefinition.audit}. */
+    audit?: boolean;
+    /** Delete rows past a retention period. Mirrors
+     *  {@link EntityDefinition.retention}. */
+    retention?: RetentionRule;
 }): EntityDefinition;
 export declare function relation(def: RelationDefinition): RelationDefinition;
 export { defineRoute } from "./route";
@@ -507,6 +560,9 @@ export interface ManifestField {
     /** Set when the field is `field.X().syncOmit()` — see
      *  [`FieldDefinition.syncOmit`]. Omitted by default. */
     syncOmit?: boolean;
+    /** Set by `.max(n)` — see [`FieldDefinition.maxLength`]. Omitted when
+     *  the field has no limit. */
+    maxLength?: number;
     /** Set when the field is `field.X().readonly()` — see
      *  [`FieldDefinition.readonly`]. Omitted by default. */
     readonly?: boolean;
@@ -571,6 +627,10 @@ export interface ManifestEntity {
     sync_limit?: number;
     /** CRDT mode; omitted when true (the runtime default). */
     crdt?: boolean;
+    /** Audit every write; omitted when false. */
+    audit?: boolean;
+    /** Retention rule; omitted when unset. */
+    retention?: RetentionRule;
 }
 export interface ManifestRoute {
     path: string;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/field-max-length.test.ts

@@ -0,0 +1,39 @@
+/**
+ * `field.string().max(n)` manifest contract:
+ *   - the limit serializes as `maxLength` (the Rust `ManifestField`
+ *     reads that key), and only when set
+ *   - it composes with the other modifiers in any order
+ *   - it is refused on non-text fields and for non-positive limits
+ */
+import { expect, test } from "bun:test";
+import { entitiesToManifest, field } from "./index";
+
+test(".max(n) serializes as maxLength on string and richtext fields", () => {
+  const [ent] = entitiesToManifest([
+    {
+      name: "Post",
+      fields: {
+        title: field.string().max(120),
+        body: field.richtext().optional().max(20_000),
+        status: field.enum(["draft", "live"]).max(5),
+        slug: field.string(),
+      },
+    },
+  ]);
+  const byName = (n: string) => ent.fields.find((f) => f.name === n)!;
+  expect(byName("title").maxLength).toBe(120);
+  expect(byName("body").maxLength).toBe(20_000);
+  expect(byName("body").optional).toBe(true);
+  expect(byName("status").maxLength).toBe(5);
+  // No limit, no key: unannotated manifests are unchanged.
+  expect("maxLength" in byName("slug")).toBe(false);
+});
+
+test(".max(n) is refused on other field types and for bad limits", () => {
+  expect(() => (field.int() as { max(n: number): unknown }).max(5)).toThrow(/field.string/);
+  expect(() => field.json().max(5)).toThrow(/field.string/);
+  expect(() => field.string().max(0)).toThrow(/positive integer/);
+  expect(() => field.string().max(1.5)).toThrow(/positive integer/);
+  expect(() => field.string().max(-1)).toThrow(/positive integer/);
+  expect(() => field.string().max(1)).not.toThrow();
+});

package/src/index.ts

@@ -101,6 +101,14 @@ export interface FieldDefinition {
    * `serverOnly`, which hides a field from ALL client surfaces.
    */
   syncOmit?: boolean;
+  /**
+   * Longest value the field accepts, in characters (Unicode code
+   * points). Set with `field.string().max(n)` or
+   * `field.richtext().max(n)`. The server rejects a longer value with
+   * `FIELD_TOO_LONG` on every write path: the entity API, sync push,
+   * `ctx.db` in functions, and collaborative (CRDT) edits.
+   */
+  maxLength?: number;
   /**
    * When true, the field is **set on insert but cannot be changed
    * by client updates**. The framework rejects any `PATCH`/`PUT`
@@ -190,6 +198,15 @@ interface FieldBuilder {
    * editor still gets it via `db.get("Variant", id)`.
    */
   syncOmit(): FieldBuilder;
+  /**
+   * Cap the value at `n` characters (Unicode code points). String and
+   * richtext fields only. See [`FieldDefinition.maxLength`].
+   *
+   * Example: `bio: field.string().max(280)` stops any client, guests
+   * included, from storing a longer bio that every other client would
+   * then sync.
+   */
+  max(n: number): FieldBuilder;
   /**
    * Mark the field as set-on-insert-only. See [`FieldDefinition.readonly`]
    * for the full semantics.
@@ -273,6 +290,17 @@ function buildField(def: FieldDefinition): FieldBuilder {
     syncOmit() {
       return buildField({ ...def, syncOmit: true });
     },
+    max(n: number) {
+      if (def.type !== "string" && def.type !== "richtext") {
+        throw new Error(
+          `.max(n) applies to field.string() and field.richtext(), not ${def.type}`,
+        );
+      }
+      if (!Number.isInteger(n) || n < 1 || n > 0xffffffff) {
+        throw new Error(`.max(n): n must be a positive integer, got ${n}`);
+      }
+      return buildField({ ...def, maxLength: n });
+    },
     readonly() {
       return buildField({ ...def, readonly: true });
     },
@@ -431,6 +459,18 @@ export interface EntityDefinition {
    * can read" and "nothing".
    */
   sync?: boolean | SyncScope;
+  /**
+   * Record every insert, update, and delete in the audit log: actor,
+   * tenant, row id, and the names of changed fields (not their values).
+   * Read it with `ctx.audit.list({ entity })` or `GET /api/admin/audit`.
+   */
+  audit?: boolean;
+  /**
+   * Delete rows once they pass a retention period. A system job runs
+   * hourly; each deletion goes through the entity pipeline and is recorded
+   * in the audit log as `retention.delete`. See {@link RetentionRule}.
+   */
+  retention?: RetentionRule;
   /**
    * Per-row CRDT (Loro) documents. Default `true`: every write merges through
    * a document, and offline edits from several devices converge. Set `false`
@@ -475,6 +515,25 @@ export interface SyncScope {
   limit?: number;
 }
 
+/**
+ * Retention rule for an entity.
+ *
+ * - `{ field: "createdAt", after: "365d" }` deletes a row once `createdAt`
+ *   is older than 365 days. Durations: `s`, `m`, `h`, `d`, `w`, `y`.
+ * - `{ field: "deleteAfter" }` (no `after`) deletes a row once
+ *   `deleteAfter` is in the past. Use it for a retention period per tenant:
+ *   set `deleteAfter` on each row at insert.
+ *
+ * `field` is a `datetime` field, or an `int`/`float` field holding unix
+ * milliseconds. Rows whose `hold` field (a `bool`) is true are kept, for
+ * example under a legal hold.
+ */
+export interface RetentionRule {
+  field: string;
+  after?: string;
+  hold?: string;
+}
+
 export function entity(
   name: string,
   fields: Record<string, FieldBuilder>,
@@ -489,6 +548,12 @@ export function entity(
     /** `false` for server-written rows that need no CRDT document. Mirrors
      *  {@link EntityDefinition.crdt}. */
     crdt?: boolean;
+    /** Record every write in the audit log. Mirrors
+     *  {@link EntityDefinition.audit}. */
+    audit?: boolean;
+    /** Delete rows past a retention period. Mirrors
+     *  {@link EntityDefinition.retention}. */
+    retention?: RetentionRule;
   },
 ): EntityDefinition {
   return {
@@ -499,6 +564,8 @@ export function entity(
     search: options?.search,
     sync: options?.sync,
     crdt: options?.crdt,
+    audit: options?.audit,
+    retention: options?.retention,
   };
 }
 
@@ -676,6 +743,9 @@ export interface ManifestField {
   /** Set when the field is `field.X().syncOmit()` — see
    *  [`FieldDefinition.syncOmit`]. Omitted by default. */
   syncOmit?: boolean;
+  /** Set by `.max(n)` — see [`FieldDefinition.maxLength`]. Omitted when
+   *  the field has no limit. */
+  maxLength?: number;
   /** Set when the field is `field.X().readonly()` — see
    *  [`FieldDefinition.readonly`]. Omitted by default. */
   readonly?: boolean;
@@ -743,6 +813,10 @@ export interface ManifestEntity {
   sync_limit?: number;
   /** CRDT mode; omitted when true (the runtime default). */
   crdt?: boolean;
+  /** Audit every write; omitted when false. */
+  audit?: boolean;
+  /** Retention rule; omitted when unset. */
+  retention?: RetentionRule;
 }
 
 export interface ManifestRoute {
@@ -1197,6 +1271,9 @@ export function entitiesToManifest(
         if (fb._def.syncOmit) {
           f.syncOmit = true;
         }
+        if (fb._def.maxLength !== undefined) {
+          f.maxLength = fb._def.maxLength;
+        }
         if (fb._def.readonly) {
           f.readonly = true;
         }
@@ -1274,6 +1351,16 @@ export function entitiesToManifest(
     if (e.crdt === false) {
       result.crdt = false;
     }
+    if (e.audit === true) {
+      result.audit = true;
+    }
+    if (e.retention) {
+      result.retention = {
+        field: e.retention.field,
+        ...(e.retention.after ? { after: e.retention.after } : {}),
+        ...(e.retention.hold ? { hold: e.retention.hold } : {}),
+      };
+    }
     return result;
   });
 }
@@ -2274,6 +2361,9 @@ function agentEntities(): EntityDefinition[] {
         // Cumulative model↔tool round-trips across every invocation of
         // this run. `maxSteps` bounds one invocation, not this.
         steps: field.int().optional(),
+        // What server code passed as `context` to ctx.agents.run; the
+        // tools receive it as `run.context`. Written by server code only.
+        context: field.json().optional(),
         createdAt: field.datetime(),
         updatedAt: field.datetime(),
       },