@gp2f/client-sdk 1.0.4 → 1.0.5

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { UndoButton } from "./UndoButton";
 export type { UndoButtonProps } from "./UndoButton";
 export { MergeModal } from "./MergeModal";
 export type { MergeModalProps } from "./MergeModal";
+export { p, PolicyBuilder, FieldBuilder, VibeBuilder } from "./policy-builder";
+export type { AstNode, Builder } from "./policy-builder";
 /**
  * The shape of the lazily-loaded policy engine module.
  *

package/dist/index.js

@@ -4,6 +4,8 @@ export { Gp2fClient, applyOptimisticUpdate } from "./client";
 export { ReconciliationBanner } from "./ReconciliationBanner";
 export { UndoButton } from "./UndoButton";
 export { MergeModal } from "./MergeModal";
+// ── Policy Builder ────────────────────────────────────────────────────────────
+export { p, PolicyBuilder, FieldBuilder, VibeBuilder } from "./policy-builder";
 /**
  * Lazily load the GP2F WASM policy engine.
  *

package/dist/policy-builder.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Fluent Policy Builder API for constructing GP2F policy AST nodes.
+ *
+ * Provides a chainable, type-safe alternative to writing raw JSON AST objects.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/user/role').eq('admin'),
+ *   p.field('/session/active').equal('true'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+/**
+ * A node in the GP2F policy AST.
+ *
+ * Mirrors `policy_core::AstNode` from Rust.
+ */
+export interface AstNode {
+    /** The operation this node performs. */
+    kind: string;
+    /** Child nodes for composite operators (And, Or, Not, comparison ops). */
+    children?: AstNode[];
+    /** JSON-pointer path used by Field and Exists nodes (e.g. `/user/role`). */
+    path?: string;
+    /** String-encoded scalar value for leaf nodes (e.g. `"admin"`, `"42"`). */
+    value?: string;
+    /** Name of the external function – used only by Call nodes. */
+    callName?: string;
+}
+/**
+ * Shared interface for all builder objects that can produce an AstNode.
+ */
+export interface Builder {
+    build(): AstNode;
+    toJSON(): AstNode;
+}
+/**
+ * A builder for field-specific policy assertions.
+ *
+ * Obtained via `p.field('/some/path')`.
+ */
+export declare class FieldBuilder implements Builder {
+    private readonly _path;
+    constructor(_path: string);
+    /** Assert that the field equals `value`. */
+    equal(value: string | number): AstNode;
+    /** Alias for {@link equal}. */
+    eq(value: string | number): AstNode;
+    /** Assert that the field does not equal `value`. */
+    notEqual(value: string | number): AstNode;
+    /** Alias for {@link notEqual}. */
+    neq(value: string | number): AstNode;
+    /** Assert that the field is greater than `value`. */
+    greaterThan(value: string | number): AstNode;
+    /** Alias for {@link greaterThan}. */
+    gt(value: string | number): AstNode;
+    /** Assert that the field is greater than or equal to `value`. */
+    greaterThanOrEqual(value: string | number): AstNode;
+    /** Alias for {@link greaterThanOrEqual}. */
+    gte(value: string | number): AstNode;
+    /** Assert that the field is less than `value`. */
+    lessThan(value: string | number): AstNode;
+    /** Alias for {@link lessThan}. */
+    lt(value: string | number): AstNode;
+    /** Assert that the field is less than or equal to `value`. */
+    lessThanOrEqual(value: string | number): AstNode;
+    /** Alias for {@link lessThanOrEqual}. */
+    lte(value: string | number): AstNode;
+    /**
+     * Assert that the field value is contained in the given array.
+     *
+     * Produces an `In` node where the left child is a Field and the right child
+     * holds the serialised array value.
+     */
+    in(values: string[]): AstNode;
+    /**
+     * Assert that the field (string or array) contains `value`.
+     *
+     * Produces a `Contains` node.
+     */
+    contains(value: string): AstNode;
+    build(): AstNode;
+    toJSON(): AstNode;
+    private _op;
+}
+/**
+ * Builder for Semantic Vibe Engine checks.
+ *
+ * Obtained via `p.vibe('intent')`.
+ */
+export declare class VibeBuilder implements Builder {
+    private readonly _intent;
+    private _threshold?;
+    constructor(_intent: string);
+    /**
+     * Set the minimum confidence threshold (0–1) for the vibe check.
+     *
+     * @example
+     * ```ts
+     * p.vibe('frustrated').withConfidence(0.8)
+     * ```
+     */
+    withConfidence(threshold: number): this;
+    build(): AstNode;
+    toJSON(): AstNode;
+}
+/**
+ * Entry point for the fluent policy builder API.
+ *
+ * All methods are static – use `p` (the shorthand export) or `PolicyBuilder`
+ * directly without instantiation.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/role').eq('admin'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+export declare class PolicyBuilder {
+    /**
+     * Begin a field assertion for the JSON-pointer `path`.
+     *
+     * Returns a {@link FieldBuilder} that can be chained with comparison
+     * operators (`eq`, `gt`, `in`, …).
+     */
+    static field(path: string): FieldBuilder;
+    /** Combine multiple nodes with a logical AND. */
+    static and(...nodes: (AstNode | Builder)[]): AstNode;
+    /** Combine multiple nodes with a logical OR. */
+    static or(...nodes: (AstNode | Builder)[]): AstNode;
+    /** Negate a node with a logical NOT. */
+    static not(node: AstNode | Builder): AstNode;
+    /** Assert that the JSON-pointer `path` exists (is non-null) in the state. */
+    static exists(path: string): AstNode;
+    /** A policy that always evaluates to `true`. */
+    static literalTrue(): AstNode;
+    /** A policy that always evaluates to `false`. */
+    static literalFalse(): AstNode;
+    /**
+     * Begin a Semantic Vibe Engine check for the given intent string.
+     *
+     * Optionally chain `.withConfidence(threshold)` before using the node.
+     */
+    static vibe(intent: string): VibeBuilder;
+}
+/**
+ * Shorthand alias for {@link PolicyBuilder}.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ * const policy = p.and(p.field('/role').eq('admin'), p.exists('/token'));
+ * ```
+ */
+export declare const p: typeof PolicyBuilder;

package/dist/policy-builder.js

@@ -0,0 +1,249 @@
+/**
+ * Fluent Policy Builder API for constructing GP2F policy AST nodes.
+ *
+ * Provides a chainable, type-safe alternative to writing raw JSON AST objects.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/user/role').eq('admin'),
+ *   p.field('/session/active').equal('true'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+// ── FieldBuilder ──────────────────────────────────────────────────────────────
+/**
+ * A builder for field-specific policy assertions.
+ *
+ * Obtained via `p.field('/some/path')`.
+ */
+export class FieldBuilder {
+    constructor(_path) {
+        this._path = _path;
+    }
+    // -- Equality --
+    /** Assert that the field equals `value`. */
+    equal(value) {
+        return this._op("Eq", String(value));
+    }
+    /** Alias for {@link equal}. */
+    eq(value) {
+        return this.equal(value);
+    }
+    /** Assert that the field does not equal `value`. */
+    notEqual(value) {
+        return this._op("Neq", String(value));
+    }
+    /** Alias for {@link notEqual}. */
+    neq(value) {
+        return this.notEqual(value);
+    }
+    // -- Comparisons --
+    /** Assert that the field is greater than `value`. */
+    greaterThan(value) {
+        return this._op("Gt", String(value));
+    }
+    /** Alias for {@link greaterThan}. */
+    gt(value) {
+        return this.greaterThan(value);
+    }
+    /** Assert that the field is greater than or equal to `value`. */
+    greaterThanOrEqual(value) {
+        return this._op("Gte", String(value));
+    }
+    /** Alias for {@link greaterThanOrEqual}. */
+    gte(value) {
+        return this.greaterThanOrEqual(value);
+    }
+    /** Assert that the field is less than `value`. */
+    lessThan(value) {
+        return this._op("Lt", String(value));
+    }
+    /** Alias for {@link lessThan}. */
+    lt(value) {
+        return this.lessThan(value);
+    }
+    /** Assert that the field is less than or equal to `value`. */
+    lessThanOrEqual(value) {
+        return this._op("Lte", String(value));
+    }
+    /** Alias for {@link lessThanOrEqual}. */
+    lte(value) {
+        return this.lessThanOrEqual(value);
+    }
+    // -- Collection --
+    /**
+     * Assert that the field value is contained in the given array.
+     *
+     * Produces an `In` node where the left child is a Field and the right child
+     * holds the serialised array value.
+     */
+    in(values) {
+        return {
+            kind: "In",
+            children: [
+                { kind: "Field", path: this._path },
+                { kind: "Literal", value: JSON.stringify(values) },
+            ],
+        };
+    }
+    /**
+     * Assert that the field (string or array) contains `value`.
+     *
+     * Produces a `Contains` node.
+     */
+    contains(value) {
+        return {
+            kind: "Contains",
+            children: [
+                { kind: "Field", path: this._path },
+                { kind: "Literal", value },
+            ],
+        };
+    }
+    // -- Builder interface --
+    build() {
+        throw new Error("FieldBuilder must be terminated with an operator (e.g. .eq(), .gt())");
+    }
+    toJSON() {
+        return this.build();
+    }
+    // -- Internal --
+    _op(kind, value) {
+        return {
+            kind,
+            children: [
+                { kind: "Field", path: this._path },
+                { kind: "Literal", value },
+            ],
+        };
+    }
+}
+// ── VibeBuilder ───────────────────────────────────────────────────────────────
+/**
+ * Builder for Semantic Vibe Engine checks.
+ *
+ * Obtained via `p.vibe('intent')`.
+ */
+export class VibeBuilder {
+    constructor(_intent) {
+        this._intent = _intent;
+    }
+    /**
+     * Set the minimum confidence threshold (0–1) for the vibe check.
+     *
+     * @example
+     * ```ts
+     * p.vibe('frustrated').withConfidence(0.8)
+     * ```
+     */
+    withConfidence(threshold) {
+        this._threshold = threshold;
+        return this;
+    }
+    build() {
+        return {
+            kind: "VibeCheck",
+            value: this._intent,
+            ...(this._threshold !== undefined
+                ? { path: String(this._threshold) }
+                : {}),
+        };
+    }
+    toJSON() {
+        return this.build();
+    }
+}
+// ── PolicyBuilder ─────────────────────────────────────────────────────────────
+/** Resolve a value that may be a raw `AstNode` or any `Builder` instance. */
+function resolve(node) {
+    return "build" in node && typeof node.build === "function"
+        ? node.build()
+        : node;
+}
+/**
+ * Entry point for the fluent policy builder API.
+ *
+ * All methods are static – use `p` (the shorthand export) or `PolicyBuilder`
+ * directly without instantiation.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/role').eq('admin'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+export class PolicyBuilder {
+    // -- Field entry point --
+    /**
+     * Begin a field assertion for the JSON-pointer `path`.
+     *
+     * Returns a {@link FieldBuilder} that can be chained with comparison
+     * operators (`eq`, `gt`, `in`, …).
+     */
+    static field(path) {
+        return new FieldBuilder(path);
+    }
+    // -- Logical operators --
+    /** Combine multiple nodes with a logical AND. */
+    static and(...nodes) {
+        return {
+            kind: "And",
+            children: nodes.map(resolve),
+        };
+    }
+    /** Combine multiple nodes with a logical OR. */
+    static or(...nodes) {
+        return {
+            kind: "Or",
+            children: nodes.map(resolve),
+        };
+    }
+    /** Negate a node with a logical NOT. */
+    static not(node) {
+        return {
+            kind: "Not",
+            children: [resolve(node)],
+        };
+    }
+    // -- Existence --
+    /** Assert that the JSON-pointer `path` exists (is non-null) in the state. */
+    static exists(path) {
+        return { kind: "Exists", path };
+    }
+    // -- Literal shortcuts --
+    /** A policy that always evaluates to `true`. */
+    static literalTrue() {
+        return { kind: "LiteralTrue" };
+    }
+    /** A policy that always evaluates to `false`. */
+    static literalFalse() {
+        return { kind: "LiteralFalse" };
+    }
+    // -- Vibe Engine --
+    /**
+     * Begin a Semantic Vibe Engine check for the given intent string.
+     *
+     * Optionally chain `.withConfidence(threshold)` before using the node.
+     */
+    static vibe(intent) {
+        return new VibeBuilder(intent);
+    }
+}
+/**
+ * Shorthand alias for {@link PolicyBuilder}.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ * const policy = p.and(p.field('/role').eq('admin'), p.exists('/token'));
+ * ```
+ */
+export const p = PolicyBuilder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gp2f/client-sdk",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "GP2F client SDK – reconciliation UX components and WebSocket client",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -24,6 +24,10 @@ export type { UndoButtonProps } from "./UndoButton";
 export { MergeModal } from "./MergeModal";
 export type { MergeModalProps } from "./MergeModal";
 
+// ── Policy Builder ────────────────────────────────────────────────────────────
+export { p, PolicyBuilder, FieldBuilder, VibeBuilder } from "./policy-builder";
+export type { AstNode, Builder } from "./policy-builder";
+
 // ── Lazy Policy Engine ────────────────────────────────────────────────────────
 
 /**

package/src/policy-builder.ts

@@ -0,0 +1,322 @@
+/**
+ * Fluent Policy Builder API for constructing GP2F policy AST nodes.
+ *
+ * Provides a chainable, type-safe alternative to writing raw JSON AST objects.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/user/role').eq('admin'),
+ *   p.field('/session/active').equal('true'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+
+// ── Shared interfaces ─────────────────────────────────────────────────────────
+
+/**
+ * A node in the GP2F policy AST.
+ *
+ * Mirrors `policy_core::AstNode` from Rust.
+ */
+export interface AstNode {
+  /** The operation this node performs. */
+  kind: string;
+  /** Child nodes for composite operators (And, Or, Not, comparison ops). */
+  children?: AstNode[];
+  /** JSON-pointer path used by Field and Exists nodes (e.g. `/user/role`). */
+  path?: string;
+  /** String-encoded scalar value for leaf nodes (e.g. `"admin"`, `"42"`). */
+  value?: string;
+  /** Name of the external function – used only by Call nodes. */
+  callName?: string;
+}
+
+/**
+ * Shared interface for all builder objects that can produce an AstNode.
+ */
+export interface Builder {
+  build(): AstNode;
+  toJSON(): AstNode;
+}
+
+// ── FieldBuilder ──────────────────────────────────────────────────────────────
+
+/**
+ * A builder for field-specific policy assertions.
+ *
+ * Obtained via `p.field('/some/path')`.
+ */
+export class FieldBuilder implements Builder {
+  constructor(private readonly _path: string) {}
+
+  // -- Equality --
+
+  /** Assert that the field equals `value`. */
+  equal(value: string | number): AstNode {
+    return this._op("Eq", String(value));
+  }
+
+  /** Alias for {@link equal}. */
+  eq(value: string | number): AstNode {
+    return this.equal(value);
+  }
+
+  /** Assert that the field does not equal `value`. */
+  notEqual(value: string | number): AstNode {
+    return this._op("Neq", String(value));
+  }
+
+  /** Alias for {@link notEqual}. */
+  neq(value: string | number): AstNode {
+    return this.notEqual(value);
+  }
+
+  // -- Comparisons --
+
+  /** Assert that the field is greater than `value`. */
+  greaterThan(value: string | number): AstNode {
+    return this._op("Gt", String(value));
+  }
+
+  /** Alias for {@link greaterThan}. */
+  gt(value: string | number): AstNode {
+    return this.greaterThan(value);
+  }
+
+  /** Assert that the field is greater than or equal to `value`. */
+  greaterThanOrEqual(value: string | number): AstNode {
+    return this._op("Gte", String(value));
+  }
+
+  /** Alias for {@link greaterThanOrEqual}. */
+  gte(value: string | number): AstNode {
+    return this.greaterThanOrEqual(value);
+  }
+
+  /** Assert that the field is less than `value`. */
+  lessThan(value: string | number): AstNode {
+    return this._op("Lt", String(value));
+  }
+
+  /** Alias for {@link lessThan}. */
+  lt(value: string | number): AstNode {
+    return this.lessThan(value);
+  }
+
+  /** Assert that the field is less than or equal to `value`. */
+  lessThanOrEqual(value: string | number): AstNode {
+    return this._op("Lte", String(value));
+  }
+
+  /** Alias for {@link lessThanOrEqual}. */
+  lte(value: string | number): AstNode {
+    return this.lessThanOrEqual(value);
+  }
+
+  // -- Collection --
+
+  /**
+   * Assert that the field value is contained in the given array.
+   *
+   * Produces an `In` node where the left child is a Field and the right child
+   * holds the serialised array value.
+   */
+  in(values: string[]): AstNode {
+    return {
+      kind: "In",
+      children: [
+        { kind: "Field", path: this._path },
+        { kind: "Literal", value: JSON.stringify(values) },
+      ],
+    };
+  }
+
+  /**
+   * Assert that the field (string or array) contains `value`.
+   *
+   * Produces a `Contains` node.
+   */
+  contains(value: string): AstNode {
+    return {
+      kind: "Contains",
+      children: [
+        { kind: "Field", path: this._path },
+        { kind: "Literal", value },
+      ],
+    };
+  }
+
+  // -- Builder interface --
+
+  build(): AstNode {
+    throw new Error(
+      "FieldBuilder must be terminated with an operator (e.g. .eq(), .gt())",
+    );
+  }
+
+  toJSON(): AstNode {
+    return this.build();
+  }
+
+  // -- Internal --
+
+  private _op(kind: string, value: string): AstNode {
+    return {
+      kind,
+      children: [
+        { kind: "Field", path: this._path },
+        { kind: "Literal", value },
+      ],
+    };
+  }
+}
+
+// ── VibeBuilder ───────────────────────────────────────────────────────────────
+
+/**
+ * Builder for Semantic Vibe Engine checks.
+ *
+ * Obtained via `p.vibe('intent')`.
+ */
+export class VibeBuilder implements Builder {
+  private _threshold?: number;
+
+  constructor(private readonly _intent: string) {}
+
+  /**
+   * Set the minimum confidence threshold (0–1) for the vibe check.
+   *
+   * @example
+   * ```ts
+   * p.vibe('frustrated').withConfidence(0.8)
+   * ```
+   */
+  withConfidence(threshold: number): this {
+    this._threshold = threshold;
+    return this;
+  }
+
+  build(): AstNode {
+    return {
+      kind: "VibeCheck",
+      value: this._intent,
+      ...(this._threshold !== undefined
+        ? { path: String(this._threshold) }
+        : {}),
+    };
+  }
+
+  toJSON(): AstNode {
+    return this.build();
+  }
+}
+
+// ── PolicyBuilder ─────────────────────────────────────────────────────────────
+
+/** Resolve a value that may be a raw `AstNode` or any `Builder` instance. */
+function resolve(node: AstNode | Builder): AstNode {
+  return "build" in node && typeof (node as Builder).build === "function"
+    ? (node as Builder).build()
+    : (node as AstNode);
+}
+
+/**
+ * Entry point for the fluent policy builder API.
+ *
+ * All methods are static – use `p` (the shorthand export) or `PolicyBuilder`
+ * directly without instantiation.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ *
+ * const policy = p.and(
+ *   p.field('/role').eq('admin'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+export class PolicyBuilder {
+  // -- Field entry point --
+
+  /**
+   * Begin a field assertion for the JSON-pointer `path`.
+   *
+   * Returns a {@link FieldBuilder} that can be chained with comparison
+   * operators (`eq`, `gt`, `in`, …).
+   */
+  static field(path: string): FieldBuilder {
+    return new FieldBuilder(path);
+  }
+
+  // -- Logical operators --
+
+  /** Combine multiple nodes with a logical AND. */
+  static and(...nodes: (AstNode | Builder)[]): AstNode {
+    return {
+      kind: "And",
+      children: nodes.map(resolve),
+    };
+  }
+
+  /** Combine multiple nodes with a logical OR. */
+  static or(...nodes: (AstNode | Builder)[]): AstNode {
+    return {
+      kind: "Or",
+      children: nodes.map(resolve),
+    };
+  }
+
+  /** Negate a node with a logical NOT. */
+  static not(node: AstNode | Builder): AstNode {
+    return {
+      kind: "Not",
+      children: [resolve(node)],
+    };
+  }
+
+  // -- Existence --
+
+  /** Assert that the JSON-pointer `path` exists (is non-null) in the state. */
+  static exists(path: string): AstNode {
+    return { kind: "Exists", path };
+  }
+
+  // -- Literal shortcuts --
+
+  /** A policy that always evaluates to `true`. */
+  static literalTrue(): AstNode {
+    return { kind: "LiteralTrue" };
+  }
+
+  /** A policy that always evaluates to `false`. */
+  static literalFalse(): AstNode {
+    return { kind: "LiteralFalse" };
+  }
+
+  // -- Vibe Engine --
+
+  /**
+   * Begin a Semantic Vibe Engine check for the given intent string.
+   *
+   * Optionally chain `.withConfidence(threshold)` before using the node.
+   */
+  static vibe(intent: string): VibeBuilder {
+    return new VibeBuilder(intent);
+  }
+}
+
+/**
+ * Shorthand alias for {@link PolicyBuilder}.
+ *
+ * @example
+ * ```ts
+ * import { p } from '@gp2f/client-sdk';
+ * const policy = p.and(p.field('/role').eq('admin'), p.exists('/token'));
+ * ```
+ */
+export const p = PolicyBuilder;