latticesql 2.1.1 → 2.2.1

package/dist/index.d.cts

@@ -1969,6 +1969,76 @@ declare class Lattice {
      */
     search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    /**
+     * Row-level-security list read for Lattice Teams (2.2). Returns only the
+     * rows of `table` that `userId` may see in team `teamId`, evaluated
+     * entirely in SQL (indexed, bounded — never "load every row then filter
+     * in JS"). A row is visible iff it has a `__lattice_row_acl` entry owned by
+     * the user or marked 'everyone', or a 'custom' entry with a matching
+     * `__lattice_row_grants` row, OR it has no ACL entry at all and the caller
+     * passes `noAclVisible` (the table default is 'everyone', or the user owns
+     * the table — the pre-2.2 / never-narrowed case). Soft-deleted rows are
+     * excluded by default; results reuse the same decrypt path as `query()`.
+     *
+     * The ACL predicate joins on the table's primary-key column cast to TEXT
+     * (ACL pks are stored as TEXT), so it is correct regardless of the user
+     * table's pk type and works on both SQLite and Postgres. The teams layer's
+     * `listVisibleRows` (src/teams/row-access.ts) is the intended caller.
+     */
+    queryVisible(table: string, opts: {
+        teamId: string;
+        userId: string;
+        /**
+         * Whether rows with NO `__lattice_row_acl` entry are visible to this
+         * user — true when the table default is 'everyone' OR the user owns the
+         * table (the pre-2.2 / never-narrowed case). Resolved by the teams layer
+         * (`listVisibleRows`); defaults to false, i.e. only rows with an explicit
+         * ACL entry granting access are returned.
+         */
+        noAclVisible?: boolean;
+        /** Soft-delete handling: 'exclude' (default), 'only' (trash), 'any'. */
+        deleted?: 'exclude' | 'only' | 'any';
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        orderDir?: 'asc' | 'desc';
+    }): Promise<Row[]>;
+    /**
+     * Visible-row counts for MANY tables in a single round-trip, using the same
+     * ACL predicate as {@link queryVisible} — so dashboard tiles agree with what
+     * the rows view lists and a physical count never reveals the existence or
+     * volume of rows the user can't see. One aggregated
+     * `SELECT (SELECT COUNT(*) …) AS c0, …` statement (no per-table fan-out, so
+     * a session pooler with few slots survives concurrent refreshes), capped at
+     * 50 tables per pass; overflow is logged and skipped (no silent truncation)
+     * and those tables count as absent — the caller renders "—". Soft-deleted
+     * rows are excluded wherever the table carries `deleted_at`, matching the
+     * default rows view.
+     */
+    countVisibleMany(specs: {
+        table: string;
+        noAclVisible: boolean;
+    }[], opts: {
+        teamId: string;
+        userId: string;
+    }): Promise<Map<string, number>>;
+    /**
+     * Hosted-sync change-log pull, filtered per recipient for 2.2 row-level
+     * security (the hosted server's sole enforcement mechanism). Returns
+     * `__lattice_change_log` rows with seq > `since` for team `teamId` that
+     * `userId` is permitted to receive:
+     *   - targeted envelopes (`recipient_user_id = userId`), plus
+     *   - broadcast envelopes (`recipient_user_id IS NULL`) that are either
+     *     table-level (`pk IS NULL` — schema / unshare, delivered to all) or
+     *     whose row is currently visible to the user via `__lattice_row_acl` /
+     *     `__lattice_row_grants` (or has no ACL entry and the table defaults to
+     *     'everyone').
+     * Ordered by seq, capped at `limit`. Raw SQL because the predicate needs
+     * OR / EXISTS that the `query()` API can't express; bounded by the seq
+     * window and indexed ACL point-lookups. Mirrors {@link queryVisible}'s
+     * visibility logic so a member never pulls the bytes of a row they can't see.
+     */
+    listChangesForRecipient(teamId: string, since: number, userId: string, limit: number): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
     sync(outputDir: string): Promise<SyncResult>;
@@ -2041,6 +2111,31 @@ declare class Lattice {
      * - `Record` → matches every PK column; all must be present in the object.
      */
     private _pkWhere;
+    private static readonly _PK_SEP;
+    /**
+     * The primary-key columns of `table` that PHYSICALLY exist, in declared
+     * order. Empty when the table has no Lattice-addressable key — e.g. a table
+     * reached via raw SQL whose PK metadata defaulted to `['id']` but that has
+     * no `id` column. Callers treat an empty result as "unkeyable" (no per-row
+     * ACL is possible, so the row-perm SQL must not reference a pk column).
+     */
+    private _resolvedPkCols;
+    /** Canonical ACL / change-log `pk` string for a row. Matches {@link _pkSqlExpr}. */
+    private _serializeRowPk;
+    /**
+     * Canonical `pk` string for a {@link PkLookup} used by update/delete, so a
+     * row addressed by lookup keys its change-log entry identically to the way
+     * {@link _serializeRowPk} keyed it at insert time.
+     */
+    private _serializePkLookup;
+    /**
+     * SQL expression reconstructing {@link _serializeRowPk} from a row aliased
+     * `t`. Returns null when the table is unkeyable (no pk columns present) — the
+     * caller must then avoid referencing a pk column at all. Dialect-aware tab
+     * separator: SQLite `char(9)`, Postgres `chr(9)` (both = U+0009), matching
+     * {@link _PK_SEP}.
+     */
+    private _pkSqlExpr;
     /**
      * Convert Filter objects into SQL clause strings and bound params.
      * An `in` filter with an empty array is silently ignored (produces no clause).
@@ -3722,6 +3817,9 @@ declare class TeamsClient {
      * members join via `redeemInvite`). Returns the new user + bearer
      * token + team summary so the caller can immediately save a
      * connection.
+     *
+     * @param teamName The workspace display name (stored as `team_name` for
+     * backward compatibility — a cloud IS a workspace with members).
      */
     register(cloudUrl: string, email: string, name: string, teamName: string): Promise<RegisterResponse>;
     redeemInvite(cloudUrl: string, inviteToken: string, email: string, name: string): Promise<RedeemResponse>;
@@ -3753,15 +3851,18 @@ declare class TeamsClient {
         };
     }>;
     /**
-     * Upgrade an already-connected cloud DB to a team DB. Two paths
-     * depending on the cloud URL's scheme:
+     * Initialize a fresh cloud DB's owner: register the first member (who
+     * becomes owner) so the cloud's members + per-table sharing surface
+     * exists. This is NOT a "convert a cloud into a team" step — a cloud
+     * workspace IS a workspace with members; this just bootstraps the owner
+     * the first time a cloud is opened. The hosted server path is the only
+     * supported one:
      *
      *   - `http(s)://…` — POST to the cloud's `/api/auth/register` endpoint
-     *     (`lattice serve --team-cloud` is fronting the Postgres).
-     *   - `postgres(ql)://…` — drive the same INSERT sequence directly
-     *     against the cloud Postgres via {@link registerDirectViaPostgres}.
-     *     The HTTP path can't be used here because the browser's Fetch
-     *     API refuses URLs with embedded credentials.
+     *     (a hosted `lattice serve` teams server is fronting the Postgres).
+     *   - `postgres(ql)://…` — rejected: direct postgres:// owner bootstrap
+     *     is deprecated. Row-level security is enforced by the hosted server,
+     *     so it is the only supported connection method for new workspaces.
      *
      * On success writes the bearer token to `~/.lattice/keys/<label>.token`
      * **and** persists the local `__lattice_team_connections` row so the
@@ -3771,9 +3872,10 @@ declare class TeamsClient {
      * the token file, leaving GUI authenticated calls with no
      * `cloud_url` + `my_user_id` + `api_token_encrypted` row to read.
      */
-    upgradeToTeamCloud(opts: {
+    registerCloudOwner(opts: {
         label: string;
         cloudUrl: string;
+        /** Workspace display name (stored as `team_name` for backward compatibility). */
         teamName: string;
         email: string;
         displayName: string;
@@ -4113,9 +4215,13 @@ declare function isPostgresUrl(url: string): boolean;
  *   - Refuses if any non-deleted user already exists on the cloud.
  *   - Refuses if the `__lattice_team_identity` singleton already exists.
  *
- * On success returns the same shape the HTTP route returns so the
- * caller (`TeamsClient.upgradeToTeamCloud`) can use either path
- * interchangeably.
+ * On success returns the same shape the HTTP route returns so a
+ * direct-postgres register can mirror the hosted register path.
+ *
+ * @deprecated Since 2.2 — new direct registrations are rejected (a direct
+ * connection bypasses row-level security). Retained only for the
+ * grandfathered existing-connection path; will be removed in 3.0. Create or
+ * join new workspaces through a hosted Teams server (an `http(s)://` URL).
  */
 declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;
 

package/dist/index.d.ts

@@ -1969,6 +1969,76 @@ declare class Lattice {
      */
     search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    /**
+     * Row-level-security list read for Lattice Teams (2.2). Returns only the
+     * rows of `table` that `userId` may see in team `teamId`, evaluated
+     * entirely in SQL (indexed, bounded — never "load every row then filter
+     * in JS"). A row is visible iff it has a `__lattice_row_acl` entry owned by
+     * the user or marked 'everyone', or a 'custom' entry with a matching
+     * `__lattice_row_grants` row, OR it has no ACL entry at all and the caller
+     * passes `noAclVisible` (the table default is 'everyone', or the user owns
+     * the table — the pre-2.2 / never-narrowed case). Soft-deleted rows are
+     * excluded by default; results reuse the same decrypt path as `query()`.
+     *
+     * The ACL predicate joins on the table's primary-key column cast to TEXT
+     * (ACL pks are stored as TEXT), so it is correct regardless of the user
+     * table's pk type and works on both SQLite and Postgres. The teams layer's
+     * `listVisibleRows` (src/teams/row-access.ts) is the intended caller.
+     */
+    queryVisible(table: string, opts: {
+        teamId: string;
+        userId: string;
+        /**
+         * Whether rows with NO `__lattice_row_acl` entry are visible to this
+         * user — true when the table default is 'everyone' OR the user owns the
+         * table (the pre-2.2 / never-narrowed case). Resolved by the teams layer
+         * (`listVisibleRows`); defaults to false, i.e. only rows with an explicit
+         * ACL entry granting access are returned.
+         */
+        noAclVisible?: boolean;
+        /** Soft-delete handling: 'exclude' (default), 'only' (trash), 'any'. */
+        deleted?: 'exclude' | 'only' | 'any';
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        orderDir?: 'asc' | 'desc';
+    }): Promise<Row[]>;
+    /**
+     * Visible-row counts for MANY tables in a single round-trip, using the same
+     * ACL predicate as {@link queryVisible} — so dashboard tiles agree with what
+     * the rows view lists and a physical count never reveals the existence or
+     * volume of rows the user can't see. One aggregated
+     * `SELECT (SELECT COUNT(*) …) AS c0, …` statement (no per-table fan-out, so
+     * a session pooler with few slots survives concurrent refreshes), capped at
+     * 50 tables per pass; overflow is logged and skipped (no silent truncation)
+     * and those tables count as absent — the caller renders "—". Soft-deleted
+     * rows are excluded wherever the table carries `deleted_at`, matching the
+     * default rows view.
+     */
+    countVisibleMany(specs: {
+        table: string;
+        noAclVisible: boolean;
+    }[], opts: {
+        teamId: string;
+        userId: string;
+    }): Promise<Map<string, number>>;
+    /**
+     * Hosted-sync change-log pull, filtered per recipient for 2.2 row-level
+     * security (the hosted server's sole enforcement mechanism). Returns
+     * `__lattice_change_log` rows with seq > `since` for team `teamId` that
+     * `userId` is permitted to receive:
+     *   - targeted envelopes (`recipient_user_id = userId`), plus
+     *   - broadcast envelopes (`recipient_user_id IS NULL`) that are either
+     *     table-level (`pk IS NULL` — schema / unshare, delivered to all) or
+     *     whose row is currently visible to the user via `__lattice_row_acl` /
+     *     `__lattice_row_grants` (or has no ACL entry and the table defaults to
+     *     'everyone').
+     * Ordered by seq, capped at `limit`. Raw SQL because the predicate needs
+     * OR / EXISTS that the `query()` API can't express; bounded by the seq
+     * window and indexed ACL point-lookups. Mirrors {@link queryVisible}'s
+     * visibility logic so a member never pulls the bytes of a row they can't see.
+     */
+    listChangesForRecipient(teamId: string, since: number, userId: string, limit: number): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
     sync(outputDir: string): Promise<SyncResult>;
@@ -2041,6 +2111,31 @@ declare class Lattice {
      * - `Record` → matches every PK column; all must be present in the object.
      */
     private _pkWhere;
+    private static readonly _PK_SEP;
+    /**
+     * The primary-key columns of `table` that PHYSICALLY exist, in declared
+     * order. Empty when the table has no Lattice-addressable key — e.g. a table
+     * reached via raw SQL whose PK metadata defaulted to `['id']` but that has
+     * no `id` column. Callers treat an empty result as "unkeyable" (no per-row
+     * ACL is possible, so the row-perm SQL must not reference a pk column).
+     */
+    private _resolvedPkCols;
+    /** Canonical ACL / change-log `pk` string for a row. Matches {@link _pkSqlExpr}. */
+    private _serializeRowPk;
+    /**
+     * Canonical `pk` string for a {@link PkLookup} used by update/delete, so a
+     * row addressed by lookup keys its change-log entry identically to the way
+     * {@link _serializeRowPk} keyed it at insert time.
+     */
+    private _serializePkLookup;
+    /**
+     * SQL expression reconstructing {@link _serializeRowPk} from a row aliased
+     * `t`. Returns null when the table is unkeyable (no pk columns present) — the
+     * caller must then avoid referencing a pk column at all. Dialect-aware tab
+     * separator: SQLite `char(9)`, Postgres `chr(9)` (both = U+0009), matching
+     * {@link _PK_SEP}.
+     */
+    private _pkSqlExpr;
     /**
      * Convert Filter objects into SQL clause strings and bound params.
      * An `in` filter with an empty array is silently ignored (produces no clause).
@@ -3722,6 +3817,9 @@ declare class TeamsClient {
      * members join via `redeemInvite`). Returns the new user + bearer
      * token + team summary so the caller can immediately save a
      * connection.
+     *
+     * @param teamName The workspace display name (stored as `team_name` for
+     * backward compatibility — a cloud IS a workspace with members).
      */
     register(cloudUrl: string, email: string, name: string, teamName: string): Promise<RegisterResponse>;
     redeemInvite(cloudUrl: string, inviteToken: string, email: string, name: string): Promise<RedeemResponse>;
@@ -3753,15 +3851,18 @@ declare class TeamsClient {
         };
     }>;
     /**
-     * Upgrade an already-connected cloud DB to a team DB. Two paths
-     * depending on the cloud URL's scheme:
+     * Initialize a fresh cloud DB's owner: register the first member (who
+     * becomes owner) so the cloud's members + per-table sharing surface
+     * exists. This is NOT a "convert a cloud into a team" step — a cloud
+     * workspace IS a workspace with members; this just bootstraps the owner
+     * the first time a cloud is opened. The hosted server path is the only
+     * supported one:
      *
      *   - `http(s)://…` — POST to the cloud's `/api/auth/register` endpoint
-     *     (`lattice serve --team-cloud` is fronting the Postgres).
-     *   - `postgres(ql)://…` — drive the same INSERT sequence directly
-     *     against the cloud Postgres via {@link registerDirectViaPostgres}.
-     *     The HTTP path can't be used here because the browser's Fetch
-     *     API refuses URLs with embedded credentials.
+     *     (a hosted `lattice serve` teams server is fronting the Postgres).
+     *   - `postgres(ql)://…` — rejected: direct postgres:// owner bootstrap
+     *     is deprecated. Row-level security is enforced by the hosted server,
+     *     so it is the only supported connection method for new workspaces.
      *
      * On success writes the bearer token to `~/.lattice/keys/<label>.token`
      * **and** persists the local `__lattice_team_connections` row so the
@@ -3771,9 +3872,10 @@ declare class TeamsClient {
      * the token file, leaving GUI authenticated calls with no
      * `cloud_url` + `my_user_id` + `api_token_encrypted` row to read.
      */
-    upgradeToTeamCloud(opts: {
+    registerCloudOwner(opts: {
         label: string;
         cloudUrl: string;
+        /** Workspace display name (stored as `team_name` for backward compatibility). */
         teamName: string;
         email: string;
         displayName: string;
@@ -4113,9 +4215,13 @@ declare function isPostgresUrl(url: string): boolean;
  *   - Refuses if any non-deleted user already exists on the cloud.
  *   - Refuses if the `__lattice_team_identity` singleton already exists.
  *
- * On success returns the same shape the HTTP route returns so the
- * caller (`TeamsClient.upgradeToTeamCloud`) can use either path
- * interchangeably.
+ * On success returns the same shape the HTTP route returns so a
+ * direct-postgres register can mirror the hosted register path.
+ *
+ * @deprecated Since 2.2 — new direct registrations are rejected (a direct
+ * connection bypasses row-level security). Retained only for the
+ * grandfathered existing-connection path; will be removed in 3.0. Create or
+ * join new workspaces through a hosted Teams server (an `http(s)://` URL).
  */
 declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;