@pylonsync/sdk 0.3.166 → 0.3.168

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.166",
+  "version": "0.3.168",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -325,7 +325,12 @@ export function action(
 // ---------------------------------------------------------------------------
 
 export interface PolicyDefinition {
-  name: string;
+  /** Optional — `buildManifest` auto-generates a name from the entity
+   *  + a counter when the fluent `.policies(policy({...}))` chain
+   *  omits one. Explicit names are still recommended for the
+   *  procedural API since they appear in policy-denied error
+   *  messages. */
+  name?: string;
   entity?: string;
   action?: string;
   /**
@@ -580,8 +585,18 @@ export function actionsToManifest(
 export function policiesToManifest(
   policies: PolicyDefinition[]
 ): ManifestPolicy[] {
-  return policies.map((p) => {
-    const result: ManifestPolicy = { name: p.name };
+  return policies.map((p, i) => {
+    const result: ManifestPolicy = {
+      // Final-resort name autogen. `buildManifest` upstream already
+      // names every attached-via-fluent policy, but a caller passing
+      // `policies: [policy({ allowRead: "..." })]` to a custom
+      // manifest builder would slip through with `name: undefined`.
+      // Stamp a unique fallback so the runtime never sees a blank.
+      name:
+        p.name && p.name.length > 0
+          ? p.name
+          : `${(p.entity ?? p.action ?? "unnamed").toLowerCase()}_p${i}`,
+    };
     if (p.allow) result.allow = p.allow;
     if (p.allowRead) result.allowRead = p.allowRead;
     if (p.allowInsert) result.allowInsert = p.allowInsert;
@@ -759,6 +774,33 @@ export function buildManifest(options: {
   policies?: PolicyDefinition[];
   auth?: ManifestAuthConfig;
 }): AppManifest {
+  // Pull policies attached via the fluent `e.entity().policies(...)`
+  // chain onto the top-level policies list. Without this, fluent
+  // apps would register entities without policies and every read
+  // would default-deny. Existing apps using the procedural API
+  // (`entity()` + separate `policy({...})` exports) are unaffected
+  // because `extractAttachedPolicies` returns an empty array for
+  // them. Concat order: top-level policies first (explicit beats
+  // attached), then anything pulled off entities.
+  //
+  // Stamp a name if the fluent caller omitted it — `name` is
+  // technically required on PolicyDefinition but the docs imply you
+  // can `.policies(policy({ allowRead: "..." }))` without one. Auto-
+  // derive from the entity + a counter so two attached policies
+  // don't collide.
+  const attached: PolicyDefinition[] = [];
+  for (const ent of options.entities) {
+    const extracted = extractAttachedPolicies(ent);
+    extracted.forEach((p, i) => {
+      attached.push({
+        ...p,
+        name: p.name && p.name.length > 0
+          ? p.name
+          : `${(p.entity ?? ent.name).toLowerCase()}_attached_${i}`,
+      });
+    });
+  }
+  const allPolicies = [...(options.policies ?? []), ...attached];
   return {
     manifest_version: MANIFEST_VERSION,
     name: options.name,
@@ -767,7 +809,7 @@ export function buildManifest(options: {
     routes: routesToManifest(options.routes),
     queries: queriesToManifest(options.queries ?? []),
     actions: actionsToManifest(options.actions ?? []),
-    policies: policiesToManifest(options.policies ?? []),
+    policies: policiesToManifest(allPolicies),
     auth: options.auth ?? auth(),
   };
 }
@@ -816,3 +858,332 @@ export {
   type StudioPageProps,
   type StudioExtensions,
 } from "./studio";
+
+// ---------------------------------------------------------------------------
+// Fluent schema API (`e` namespace)
+//
+// `entity(name, fields, options)` + `field.*` + `policy({...})` are the
+// stable foundation — every dependent app uses them today. The fluent
+// API below sits on top and compiles down to the same EntityDefinition
+// + PolicyDefinition shapes the runtime already understands, so both
+// styles can coexist forever. The fluent shape just reads better in
+// docs + marketing snippets:
+//
+// ```ts
+// export const Order = e.entity("Order", {
+//   customer:  field.id("Customer"),
+//   total:     field.int(),
+//   status:    field.enum(["pending", "paid", "failed"]),
+//   createdAt: field.datetime().defaultNow(),
+// })
+//   .indexes(e.idx("customer", "createdAt"), e.idx("status"))
+//   .policies(policy({
+//     allowRead:  "auth.userId == data.customer || auth.hasRole('admin')",
+//     allowUpdate: "auth.hasRole('admin')",
+//   }))
+//   .behaviors([timestamps, softDelete]);
+// ```
+//
+// Behaviors are field-injection helpers. `timestamps` adds
+// `createdAt` + `updatedAt` to the entity fields; `softDelete` adds
+// `deletedAt`. They mutate the EntityDefinition's fields before the
+// runtime sees it, so the rest of the framework (storage, sync,
+// policy gates) treats them as ordinary columns. Auto-stamping
+// (filling `now()` on insert/update) needs runtime support — landing
+// in a follow-up patch via the `defaultExpr: "now"` marker the
+// builder records.
+// ---------------------------------------------------------------------------
+
+/**
+ * Behavior — a function that mutates the entity definition before it's
+ * registered. Implementations should be idempotent (the user can list
+ * the same behavior twice without breaking the schema).
+ */
+export interface Behavior {
+  /** Stable identifier — surfaced in the manifest for tooling, lets a
+   *  pass-through inspector see which behaviors are active. */
+  readonly id: string;
+  apply(def: EntityDefinition): EntityDefinition;
+}
+
+/**
+ * `timestamps` — auto-add `createdAt` + `updatedAt` datetime fields.
+ * The `defaultNow()` marker on each tells the runtime to fill `now()`
+ * on insert (and on update for `updatedAt`). Wiring lands with the
+ * runtime patch — until then, app code can still set the values
+ * manually and the fields exist on the row.
+ */
+export const timestamps: Behavior = {
+  id: "timestamps",
+  apply(def) {
+    const fields = { ...def.fields };
+    if (!fields.createdAt) {
+      fields.createdAt = (field.datetime() as FieldBuilder & {
+        defaultNow?: () => FieldBuilder;
+      }).defaultNow?.() ?? field.datetime();
+    }
+    if (!fields.updatedAt) {
+      fields.updatedAt = (field.datetime() as FieldBuilder & {
+        defaultNow?: () => FieldBuilder;
+        updateOnWrite?: () => FieldBuilder;
+      }).defaultNow?.() ?? field.datetime();
+    }
+    return { ...def, fields };
+  },
+};
+
+/**
+ * `softDelete` — auto-add a nullable `deletedAt` datetime field.
+ * Rows with `deletedAt != null` are filtered from default reads
+ * (TS-side filtering today; runtime filter lands in the follow-up).
+ */
+export const softDelete: Behavior = {
+  id: "softDelete",
+  apply(def) {
+    const fields = { ...def.fields };
+    if (!fields.deletedAt) {
+      fields.deletedAt = field.datetime().optional();
+    }
+    return { ...def, fields };
+  },
+};
+
+/**
+ * `audit` — marker behavior. Tags the entity for the framework's
+ * audit pipeline (writes an `AuditEvent` row per mutation, recording
+ * the actor + diff). Runtime hook lands in a follow-up patch — for
+ * now the marker is preserved on the manifest so apps can opt in
+ * early without breaking later.
+ */
+export const audit: Behavior = {
+  id: "audit",
+  apply(def) {
+    // No field injection today. The behavior flag is recorded via
+    // the EntityBuilder's `_behaviors` list (read off on serialize)
+    // so the runtime can pick it up once the audit pipeline lands.
+    return def;
+  },
+};
+
+/**
+ * Internal sentinel — apps don't construct these directly. The
+ * `field.X` builders gain `default(val)` / `defaultNow()` chainables
+ * below; this is just the shape stored on the field definition for
+ * the runtime to read.
+ */
+type DefaultMarker = { kind: "value"; value: unknown } | { kind: "now" };
+
+/**
+ * Augment FieldBuilder with the new `default()` / `defaultNow()`
+ * chainables. Runtime support for actually filling these values on
+ * insert lands as part of v0.4.1; until then the markers are
+ * recorded in the manifest for tooling + the codegen layer.
+ */
+declare module "./index" {
+  // (Empty — the `default*` methods are added at runtime via the
+  // patched buildField below. Apps see them via the FieldBuilder
+  // surface declared above.)
+}
+
+// Field builder with chainable `.default()` / `.defaultNow()`. All
+// other chainables (`optional`, `unique`, `crdt`, `serverOnly`,
+// `readonly`) are reimplemented here to return another
+// `buildFieldWithDefaults` — without this, calling `.optional()`
+// after `.default()` would drop the default markers off the chain
+// (codex Wave-3 review: the previous `{ ...base, default, defaultNow }`
+// pattern delegated optional/unique to the original buildField which
+// returned a builder lacking `.default()`). Recursion through the
+// same constructor keeps the surface stable regardless of chain
+// order.
+function buildFieldWithDefaults(
+  def: FieldDefinition & {
+    default?: DefaultMarker;
+    enumValues?: readonly string[];
+  },
+): FieldBuilder & {
+  default(value: unknown): ReturnType<typeof buildFieldWithDefaults>;
+  defaultNow(): ReturnType<typeof buildFieldWithDefaults>;
+} {
+  return {
+    _def: def,
+    optional() {
+      return buildFieldWithDefaults({ ...def, optional: true });
+    },
+    unique() {
+      return buildFieldWithDefaults({ ...def, unique: true });
+    },
+    crdt(annotation) {
+      return buildFieldWithDefaults({ ...def, crdt: annotation });
+    },
+    serverOnly() {
+      return buildFieldWithDefaults({ ...def, serverOnly: true });
+    },
+    readonly() {
+      return buildFieldWithDefaults({ ...def, readonly: true });
+    },
+    default(value: unknown) {
+      return buildFieldWithDefaults({
+        ...def,
+        default: { kind: "value", value },
+      });
+    },
+    defaultNow() {
+      return buildFieldWithDefaults({ ...def, default: { kind: "now" } });
+    },
+  };
+}
+// Re-export `field` with the patched builder so callers picking up
+// the new SDK get the chainables transparently. The old `field`
+// surface still works — `.default()` / `.defaultNow()` are additive.
+// We intentionally re-export from the same name so existing imports
+// (`import { field } from "@pylonsync/sdk"`) keep working AND gain
+// the new methods without a code change.
+Object.assign(field, {
+  string: () => buildFieldWithDefaults({ type: "string", optional: false, unique: false }),
+  int: () => buildFieldWithDefaults({ type: "int", optional: false, unique: false }),
+  float: () => buildFieldWithDefaults({ type: "float", optional: false, unique: false }),
+  number: () => buildFieldWithDefaults({ type: "float", optional: false, unique: false }),
+  bool: () => buildFieldWithDefaults({ type: "bool", optional: false, unique: false }),
+  boolean: () => buildFieldWithDefaults({ type: "bool", optional: false, unique: false }),
+  datetime: () => buildFieldWithDefaults({ type: "datetime", optional: false, unique: false }),
+  richtext: () => buildFieldWithDefaults({ type: "richtext", optional: false, unique: false }),
+  id: (target: string) => buildFieldWithDefaults({ type: `id(${target})` as FieldType, optional: false, unique: false }),
+  /**
+   * `field.enum(["pending", "paid", "failed"])` — stored as a string
+   * with allowed-values metadata. Runtime enforcement (CHECK
+   * constraint or insert-time validation) lands in a follow-up
+   * patch; for now the values flow through to codegen so the
+   * generated client gets a precise `"pending" | "paid" | "failed"`
+   * literal-union type instead of a wide `string`.
+   */
+  enum(values: readonly string[]) {
+    const def: FieldDefinition & { enumValues?: readonly string[] } = {
+      type: "string",
+      optional: false,
+      unique: false,
+      enumValues: values,
+    };
+    return buildFieldWithDefaults(def);
+  },
+});
+
+/** Variadic index helper — `e.idx("customer", "createdAt")` reads
+ *  better than the options-object form for the common case. */
+function idx(...fields: string[]): IndexDefinition {
+  return {
+    name: `by_${fields.join("_")}`,
+    fields,
+    unique: false,
+  };
+}
+
+interface EntityBuilder {
+  readonly _def: EntityDefinition & { behaviors?: string[] };
+  indexes(...idxs: IndexDefinition[]): EntityBuilder;
+  policies(...policies: PolicyDefinition[]): EntityBuilder;
+  behaviors(list: readonly Behavior[]): EntityBuilder;
+  relations(...rels: RelationDefinition[]): EntityBuilder;
+  search(cfg: SearchConfig): EntityBuilder;
+}
+
+/**
+ * Internal — `e.entity()` is the public surface. Wraps an
+ * EntityDefinition with chainable builders that all return another
+ * EntityBuilder so the fluent calls compose freely. The terminal
+ * call is implicit: any place the framework expects an
+ * EntityDefinition (e.g. `entities: [...]` on the manifest), the
+ * builder unwraps via the `_def` getter on access.
+ */
+function buildEntity(def: EntityDefinition & { behaviors?: string[] }): EntityBuilder {
+  const self: EntityBuilder = {
+    get _def() {
+      return def;
+    },
+    indexes(...idxs) {
+      return buildEntity({
+        ...def,
+        indexes: [...(def.indexes ?? []), ...idxs],
+      });
+    },
+    policies(..._policies) {
+      // Policies aren't carried on the EntityDefinition itself —
+      // they live in the manifest's top-level `policies` list. We
+      // store them under a non-standard key here so the manifest
+      // builder can pluck them off; the export shape stays
+      // EntityDefinition-compatible.
+      const carried = { ...(def as EntityDefinition & { _attachedPolicies?: PolicyDefinition[] }) };
+      const existing = carried._attachedPolicies ?? [];
+      const stamped = _policies.map((p) => ({
+        ...p,
+        // Auto-bind the entity if the policy didn't specify one —
+        // this is the whole point of attaching policies via the
+        // builder: don't repeat the entity name.
+        entity: p.entity ?? def.name,
+      }));
+      carried._attachedPolicies = [...existing, ...stamped];
+      return buildEntity(carried);
+    },
+    behaviors(list) {
+      let next = def;
+      for (const b of list) {
+        next = b.apply(next);
+      }
+      return buildEntity({
+        ...next,
+        behaviors: [...(def.behaviors ?? []), ...list.map((b) => b.id)],
+      });
+    },
+    relations(...rels) {
+      return buildEntity({
+        ...def,
+        relations: [...(def.relations ?? []), ...rels],
+      });
+    },
+    search(cfg) {
+      return buildEntity({
+        ...def,
+        search: cfg,
+      });
+    },
+  };
+
+  // Spread `def` keys onto the builder so anywhere the framework
+  // expects an EntityDefinition shape (name, fields, indexes, etc.)
+  // sees them directly without unwrapping. Manifest builder paths
+  // walk `.name` and `.fields` straight off the builder.
+  Object.assign(self, def);
+  return self;
+}
+
+/**
+ * The fluent `e` namespace. Equivalent to the procedural `entity()`
+ * function — both produce manifest-compatible definitions, both can
+ * be mixed in the same app.
+ */
+export const e = {
+  entity(
+    name: string,
+    fields: Record<string, FieldBuilder>,
+  ): EntityBuilder {
+    return buildEntity({ name, fields });
+  },
+  idx,
+};
+
+/**
+ * Extract attached policies from a fluent entity. The manifest
+ * builder calls this when assembling the top-level `policies` list,
+ * so apps using the fluent `.policies(...)` chain don't have to
+ * register policies separately at the manifest root.
+ *
+ * Returns an empty array for entities produced by the procedural
+ * `entity()` API — those apps register policies the old way.
+ */
+export function extractAttachedPolicies(
+  e: EntityDefinition | EntityBuilder,
+): PolicyDefinition[] {
+  const carried = (e as EntityDefinition & {
+    _attachedPolicies?: PolicyDefinition[];
+  })._attachedPolicies;
+  return carried ?? [];
+}