@objectstack/client 4.0.3 → 4.0.5

package/dist/index.mjs

@@ -1,6 +1,6 @@
 // src/index.ts
 import { isFilterAST } from "@objectstack/spec/data";
-import { createLogger } from "@objectstack/core";
+import { createLogger } from "@objectstack/core/logger";
 
 // src/realtime-api.ts
 var RealtimeAPI = class {
@@ -631,10 +631,637 @@ var ObjectStackClient = class {
         return this.unwrapResponse(res);
       }
     };
+    /**
+     * Environment Management Services
+     *
+     * Environments are the v4.1+ isolation primitive — each project owns a
+     * physically separate data-plane database. All Studio-level switching goes
+     * through this API.
+     *
+     * Endpoints:
+     * - GET    /api/v1/cloud/projects            → list environments
+     * - GET    /api/v1/cloud/projects/:id        → get one (with database info)
+     * - POST   /api/v1/cloud/projects            → provision a new project
+     * - PATCH  /api/v1/cloud/projects/:id        → update (displayName, plan, status, …)
+     * - POST   /api/v1/cloud/projects/:id/activate → set as session's active project
+     * - POST   /api/v1/cloud/projects/:id/credentials/rotate → rotate credential
+     *
+     * @see docs/adr/0002-project-database-isolation.md
+     */
+    this.projects = {
+      /**
+       * List environments visible to the current session. Optionally filter
+       * by organization (control-plane query — not routed through a data-plane DB).
+       */
+      list: async (filters) => {
+        const params = new URLSearchParams();
+        if (filters?.organization_id) params.set("organizationId", filters.organization_id);
+        if (filters?.env_type) params.set("envType", filters.env_type);
+        if (filters?.status) params.set("status", filters.status);
+        const qs = params.toString();
+        const url = `${this.baseUrl}/api/v1/cloud/projects${qs ? "?" + qs : ""}`;
+        const res = await this.fetch(url);
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Get a single project (joined with its database and membership row).
+       */
+      get: async (id) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}`);
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Provision a new project. Delegates to
+       * `ProjectProvisioningService.provisionProject` on the server.
+       */
+      create: async (req) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Update a project (display_name, plan, status, is_default, metadata).
+       */
+      update: async (id, patch) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}`, {
+          method: "PATCH",
+          body: JSON.stringify(patch)
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Cascade-delete a project: cleans up credential/member/package_installation
+       * rows, releases the physical database via the provisioning adapter, and
+       * removes the `sys_project` row. Default projects require `force: true`.
+       */
+      delete: async (id, opts) => {
+        const qs = opts?.force ? "?force=1" : "";
+        const res = await this.fetch(
+          `${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}${qs}`,
+          { method: "DELETE" }
+        );
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Activate this project for the current session. The server writes
+       * `active_environment_id` on the better-auth session; subsequent requests
+       * are routed to this project's database.
+       */
+      activate: async (id) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}/activate`, {
+          method: "POST"
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Rotate the active database credential for this project.
+       */
+      rotateCredential: async (id, plaintext) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}/credentials/rotate`, {
+          method: "POST",
+          body: JSON.stringify({ plaintext })
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Update the hostname bound to this project. Validates format and
+       * uniqueness server-side; invalidates the dispatcher's routing cache.
+       */
+      updateHostname: async (id, hostname) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}/hostname`, {
+          method: "POST",
+          body: JSON.stringify({ hostname })
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Retry provisioning for a project stuck in `failed` (or
+       * `provisioning`) state. The server re-runs the driver handshake; on
+       * success the project flips to `active`, on failure it stays
+       * `failed` with `metadata.provisioningError` updated.
+       */
+      retryProvisioning: async (id) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}/retry`, {
+          method: "POST"
+        });
+        return this.unwrapResponse(res);
+      },
+      /**
+       * List members of a project (per-project RBAC).
+       */
+      listMembers: async (id) => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(id)}/members`);
+        return this.unwrapResponse(res);
+      },
+      /**
+       * List ObjectQL drivers registered on the server. Useful for populating a
+       * driver selector when provisioning a new project (memory / turso /
+       * future sql drivers). Returned `name` is the short alias (e.g. `memory`,
+       * `turso`); `driverId` is the full FQN (e.g. `com.objectstack.driver.memory`).
+       */
+      listDrivers: async () => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/drivers`);
+        return this.unwrapResponse(res);
+      },
+      /**
+       * List available project templates. Templates are seeded into the project
+       * database once at provisioning time when `template_id` is supplied.
+       */
+      listTemplates: async () => {
+        const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/templates`);
+        return this.unwrapResponse(res);
+      },
+      /**
+       * Per-project package installation management (Power Apps "solution" model).
+       * Install records are stored in the environment's own database.
+       */
+      packages: {
+        /** List all packages installed in a specific project. */
+        list: async (envId) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages`);
+          return this.unwrapResponse(res);
+        },
+        /** Install a package into the project. */
+        install: async (envId, body) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages`, {
+            method: "POST",
+            body: JSON.stringify(body)
+          });
+          return this.unwrapResponse(res);
+        },
+        /** Get a single installation record. */
+        get: async (envId, pkgId) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages/${encodeURIComponent(pkgId)}`);
+          return this.unwrapResponse(res);
+        },
+        /** Enable a previously disabled package. */
+        enable: async (envId, pkgId) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages/${encodeURIComponent(pkgId)}/enable`, {
+            method: "PATCH"
+          });
+          return this.unwrapResponse(res);
+        },
+        /** Disable an installed package (metadata will not be loaded). */
+        disable: async (envId, pkgId) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages/${encodeURIComponent(pkgId)}/disable`, {
+            method: "PATCH"
+          });
+          return this.unwrapResponse(res);
+        },
+        /** Uninstall a package from the project. Forbidden for scope=platform packages. */
+        uninstall: async (envId, pkgId) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages/${encodeURIComponent(pkgId)}`, {
+            method: "DELETE"
+          });
+          return this.unwrapResponse(res);
+        },
+        /** Upgrade an installed package to a newer version. */
+        upgrade: async (envId, pkgId, targetVersion) => {
+          const res = await this.fetch(`${this.baseUrl}/api/v1/cloud/projects/${encodeURIComponent(envId)}/packages/${encodeURIComponent(pkgId)}/upgrade`, {
+            method: "POST",
+            body: JSON.stringify({ targetVersion })
+          });
+          return this.unwrapResponse(res);
+        }
+      }
+    };
+    /**
+     * Organization Services
+     *
+     * Thin wrapper around better-auth's organization plugin endpoints, which
+     * are mounted under `/api/v1/auth/organization/**`. Used by the Studio
+     * OrganizationSwitcher and the /orgs management routes.
+     */
+    this.organizations = {
+      /**
+       * List organizations the current user belongs to.
+       * GET /api/v1/auth/organization/list
+       */
+      list: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/list`);
+        const data = await res.json();
+        const orgs = Array.isArray(data) ? data : data?.data ?? [];
+        return { organizations: orgs };
+      },
+      /**
+       * Create a new organization.
+       * POST /api/v1/auth/organization/create
+       */
+      create: async (req) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/create`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
+      },
+      /**
+       * Update an existing organization.
+       * POST /api/v1/auth/organization/update
+       *
+       * better-auth requires the caller to be an owner/admin (server-side
+       * enforcement); the body shape is `{ organizationId, data: {...} }`.
+       */
+      update: async (organizationId, data) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/update`, {
+          method: "POST",
+          body: JSON.stringify({ organizationId, data })
+        });
+        return res.json();
+      },
+      /**
+       * Set the active organization on the current session. The server writes
+       * `activeOrganizationId` on the better-auth session, which downstream
+       * handlers (e.g. `EnvironmentProvisioningService`) consult.
+       *
+       * POST /api/v1/auth/organization/set-active
+       */
+      setActive: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/set-active`, {
+          method: "POST",
+          body: JSON.stringify({ organizationId })
+        });
+        return res.json();
+      },
+      /**
+       * Get full organization detail (members, invitations, teams).
+       * GET /api/v1/auth/organization/get-full-organization?organizationId=...
+       */
+      get: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(
+          `${this.baseUrl}${route}/organization/get-full-organization?organizationId=${encodeURIComponent(organizationId)}`
+        );
+        return res.json();
+      },
+      /**
+       * List members of an organization.
+       */
+      listMembers: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(
+          `${this.baseUrl}${route}/organization/list-members?organizationId=${encodeURIComponent(organizationId)}`
+        );
+        return res.json();
+      },
+      /**
+       * Invite a user to the organization.
+       */
+      invite: async (req) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/invite-member`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
+      },
+      /**
+       * Leave the given organization.
+       */
+      leave: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/leave`, {
+          method: "POST",
+          body: JSON.stringify({ organizationId })
+        });
+        return res.json();
+      },
+      /**
+       * Delete an organization via better-auth's organization plugin.
+       *
+       * POST /api/v1/auth/organization/delete
+       *
+       * better-auth removes the organization row, all members, and all
+       * pending invitations. Project teardown (per-project DBs, etc.) is
+       * handled server-side by hooks attached to the organization plugin.
+       */
+      delete: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/delete`, {
+          method: "POST",
+          body: JSON.stringify({ organizationId })
+        });
+        return res.json();
+      },
+      /**
+       * Remove a member from an organization.
+       *
+       * better-auth: POST /organization/remove-member
+       * Body: `{ memberIdOrEmail, organizationId? }` — note the parameter is the
+       * **member id** (the row id from `member` table) or the user's email; it
+       * is *not* the bare `userId`. Server enforces owner/admin permission.
+       */
+      removeMember: async (organizationId, params) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/remove-member`, {
+          method: "POST",
+          body: JSON.stringify({ memberIdOrEmail: params.memberIdOrEmail, organizationId })
+        });
+        return res.json();
+      },
+      /**
+       * Change a member's role in an organization (owner/admin only).
+       *
+       * better-auth: POST /organization/update-member-role
+       * Body: `{ memberId, role, organizationId? }`. The `memberId` is the
+       * `member` table row id (not user id). `role` is one of the configured
+       * organisation roles (default: `owner | admin | member`).
+       */
+      updateMemberRole: async (organizationId, params) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/organization/update-member-role`, {
+          method: "POST",
+          body: JSON.stringify({ memberId: params.memberId, role: params.role, organizationId })
+        });
+        return res.json();
+      },
+      /**
+       * Look up the calling user's membership row in the given organisation.
+       * Useful for permission checks on the client without having to scan the
+       * full member list.
+       *
+       * better-auth: GET /organization/get-active-member?organizationId=…
+       */
+      getActiveMember: async (organizationId) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(
+          `${this.baseUrl}${route}/organization/get-active-member?organizationId=${encodeURIComponent(organizationId)}`
+        );
+        return res.json();
+      },
+      /**
+       * Invitation lifecycle — wraps better-auth's organization-plugin
+       * invitation endpoints. Always go through here instead of writing to
+       * `sys_invitation` via the data API: the better-auth writers handle
+       * status transitions, expiry, dedupe, and the `sendInvitationEmail`
+       * side-effect that the auth-manager wires up.
+       */
+      invitations: {
+        /**
+         * List pending/accepted/canceled invitations for an organization.
+         * Requires owner/admin role on that org.
+         *
+         * better-auth: GET /organization/list-invitations?organizationId=…
+         */
+        list: async (organizationId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(
+            `${this.baseUrl}${route}/organization/list-invitations?organizationId=${encodeURIComponent(organizationId)}`
+          );
+          const data = await res.json();
+          const invitations = Array.isArray(data) ? data : data?.data ?? data?.invitations ?? [];
+          return { invitations };
+        },
+        /**
+         * List the **current user's** incoming invitations across every
+         * organisation. Used by the per-user "Invitations" inbox page.
+         *
+         * better-auth: GET /organization/list-user-invitations
+         */
+        listMine: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/list-user-invitations`);
+          const data = await res.json();
+          const invitations = Array.isArray(data) ? data : data?.data ?? data?.invitations ?? [];
+          return { invitations };
+        },
+        /** better-auth: POST /organization/cancel-invitation */
+        cancel: async (invitationId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/cancel-invitation`, {
+            method: "POST",
+            body: JSON.stringify({ invitationId })
+          });
+          return res.json();
+        },
+        /** better-auth: POST /organization/accept-invitation */
+        accept: async (invitationId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/accept-invitation`, {
+            method: "POST",
+            body: JSON.stringify({ invitationId })
+          });
+          return res.json();
+        },
+        /** better-auth: POST /organization/reject-invitation */
+        reject: async (invitationId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/reject-invitation`, {
+            method: "POST",
+            body: JSON.stringify({ invitationId })
+          });
+          return res.json();
+        },
+        /**
+         * "Resend" an invitation. better-auth has no first-class resend
+         * endpoint, so we implement it as cancel-then-invite: cancel the old
+         * row (so its status flips to `canceled` and audit hooks fire), then
+         * issue a fresh invite. The new invite re-runs `sendInvitationEmail`
+         * on the server, so the recipient gets a brand-new accept URL.
+         *
+         * If `cancel()` fails (e.g. invite already accepted) the error is
+         * re-thrown without re-inviting.
+         */
+        resend: async (invitation) => {
+          if (invitation.id) {
+            try {
+              await this.organizations.invitations.cancel(invitation.id);
+            } catch {
+            }
+          }
+          return this.organizations.invite({
+            email: invitation.email,
+            role: invitation.role ?? "member",
+            organizationId: invitation.organizationId
+          });
+        }
+      },
+      /**
+       * Team management — only available when the organisation plugin is
+       * configured with `teams: { enabled: true }` on the server. Calls return
+       * a 4xx if teams aren't enabled; UI should hide the section in that case.
+       */
+      teams: {
+        /** better-auth: GET /organization/list-teams?organizationId=… */
+        list: async (organizationId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(
+            `${this.baseUrl}${route}/organization/list-teams?organizationId=${encodeURIComponent(organizationId)}`
+          );
+          const data = await res.json();
+          const teams = Array.isArray(data) ? data : data?.data ?? data?.teams ?? [];
+          return { teams };
+        },
+        /** better-auth: POST /organization/create-team */
+        create: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/create-team`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        },
+        /** better-auth: POST /organization/update-team */
+        update: async (params) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/update-team`, {
+            method: "POST",
+            body: JSON.stringify(params)
+          });
+          return res.json();
+        },
+        /** better-auth: POST /organization/remove-team */
+        delete: async (params) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/remove-team`, {
+            method: "POST",
+            body: JSON.stringify(params)
+          });
+          return res.json();
+        },
+        /** better-auth: GET /organization/list-team-members?teamId=… */
+        listMembers: async (teamId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(
+            `${this.baseUrl}${route}/organization/list-team-members?teamId=${encodeURIComponent(teamId)}`
+          );
+          const data = await res.json();
+          const members = Array.isArray(data) ? data : data?.data ?? data?.members ?? [];
+          return { members };
+        },
+        /** better-auth: POST /organization/add-team-member */
+        addMember: async (params) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/add-team-member`, {
+            method: "POST",
+            body: JSON.stringify(params)
+          });
+          return res.json();
+        },
+        /** better-auth: POST /organization/remove-team-member */
+        removeMember: async (params) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/organization/remove-team-member`, {
+            method: "POST",
+            body: JSON.stringify(params)
+          });
+          return res.json();
+        }
+      }
+    };
+    /**
+     * OAuth / OpenID Connect Provider — admin endpoints exposed by
+     * `@better-auth/oauth-provider` (when enabled on the server). Lets users
+     * register their own OAuth client applications, list them, and revoke them.
+     *
+     * All endpoints are mounted under the auth route, e.g. `/api/v1/auth/oauth2/*`.
+     */
+    this.oauth = {
+      applications: {
+        /**
+         * Register a new OAuth client application.
+         * POST /api/v1/auth/oauth2/create-client (authenticated)
+         *
+         * Returns the freshly-issued `client_id` and `client_secret`.
+         * The secret is only returned at creation time — store it securely.
+         */
+        register: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/oauth2/create-client`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        },
+        /**
+         * Get a single OAuth application by its `client_id`.
+         * GET /api/v1/auth/oauth2/get-client?client_id=...
+         */
+        get: async (clientId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(
+            `${this.baseUrl}${route}/oauth2/get-client?client_id=${encodeURIComponent(clientId)}`
+          );
+          return res.json();
+        },
+        /**
+         * Get a single OAuth application's public fields (no auth required
+         * once the user has signed in). Used by the consent screen.
+         * GET /api/v1/auth/oauth2/public-client?client_id=...
+         */
+        getPublic: async (clientId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(
+            `${this.baseUrl}${route}/oauth2/public-client?client_id=${encodeURIComponent(clientId)}`
+          );
+          return res.json();
+        },
+        /**
+         * List OAuth applications visible to the current user.
+         *
+         * Uses `@better-auth/oauth-provider`'s `/oauth2/get-clients` endpoint
+         * which returns clients owned by the current user (and their
+         * organization, if applicable).
+         */
+        list: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/oauth2/get-clients`);
+          const data = await res.json();
+          const items = Array.isArray(data) ? data : data?.clients ?? data?.data ?? [];
+          return { applications: items };
+        },
+        /**
+         * Delete an OAuth application by its `client_id`.
+         * POST /api/v1/auth/oauth2/delete-client
+         *
+         * Tokens and consents referencing the client cascade-delete via the
+         * better-auth schema's `onDelete: cascade` foreign keys.
+         */
+        delete: async (clientId) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/oauth2/delete-client`, {
+            method: "POST",
+            body: JSON.stringify({ client_id: clientId })
+          });
+          return res.json();
+        }
+      },
+      /**
+       * Submit the user's decision to a pending consent request.
+       * POST /api/v1/auth/oauth2/consent
+       *
+       * Called by the consent screen after the user accepts or denies. The
+       * `oauth_query` is the raw query string of the consent page URL — it
+       * carries the signed authorization request that the consent endpoint
+       * verifies before issuing the authorization code.
+       */
+      consent: async (req) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/oauth2/consent`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
+      }
+    };
     /**
      * Authentication Services
      */
     this.auth = {
+      /**
+       * Get authentication configuration
+       * Returns available auth providers and features
+       */
+      getConfig: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/config`);
+        return this.unwrapResponse(res);
+      },
       /**
        * Login with email and password
        * Uses better-auth endpoint: POST /sign-in/email
@@ -643,8 +1270,100 @@ var ObjectStackClient = class {
         const route = this.getRoute("auth");
         const res = await this.fetch(`${this.baseUrl}${route}/sign-in/email`, {
           method: "POST",
+          headers: { Origin: this.baseUrl },
           body: JSON.stringify(request)
         });
+        const raw = await res.json();
+        const data = raw && (raw.data ?? (raw.token || raw.user ? { token: raw.token, user: raw.user } : void 0));
+        const normalized = data ? { ...raw, data } : raw;
+        if (normalized.data?.token) {
+          this.token = normalized.data.token;
+        }
+        return normalized;
+      },
+      /**
+       * Logout current user
+       * Uses better-auth endpoint: POST /sign-out
+       */
+      logout: async () => {
+        const route = this.getRoute("auth");
+        await this.fetch(`${this.baseUrl}${route}/sign-out`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Origin: this.baseUrl },
+          body: "{}"
+        });
+        this.token = void 0;
+      },
+      /**
+       * Get current user session
+       * Uses better-auth endpoint: GET /get-session
+       */
+      me: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/get-session`, {
+          headers: { Origin: this.baseUrl }
+        });
+        return res.json();
+      },
+      /**
+       * Register a new user account
+       * Uses better-auth endpoint: POST /sign-up/email
+       */
+      register: async (request) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/sign-up/email`, {
+          method: "POST",
+          headers: { Origin: this.baseUrl },
+          body: JSON.stringify(request)
+        });
+        const raw = await res.json();
+        const data = raw && (raw.data ?? (raw.token || raw.user ? { token: raw.token, user: raw.user } : void 0));
+        const normalized = data ? { ...raw, data } : raw;
+        if (normalized.data?.token) {
+          this.token = normalized.data.token;
+        }
+        return normalized;
+      },
+      /**
+       * Initiate OAuth sign-in via a social or OIDC provider.
+       *
+       * - Social providers (Google, GitHub, etc.): calls POST /sign-in/social with `{ provider }`.
+       * - OIDC/enterprise providers: calls POST /sign-in/oauth2 with `{ providerId }`.
+       *
+       * After the provider callback better-auth sets the session cookie and redirects to `callbackURL`.
+       */
+      signInWithProvider: async (provider, opts) => {
+        if (typeof window === "undefined") {
+          throw new Error("signInWithProvider requires a browser environment");
+        }
+        const route = this.getRoute("auth");
+        const callbackURL = opts?.callbackURL ?? window.location.origin + "/login";
+        const isOidc = opts?.type === "oidc";
+        const endpoint = isOidc ? "/sign-in/oauth2" : "/sign-in/social";
+        const body = isOidc ? { providerId: provider, callbackURL } : { provider, callbackURL };
+        if (opts?.errorCallbackURL) body.errorCallbackURL = opts.errorCallbackURL;
+        const res = await this.fetch(`${this.baseUrl}${route}${endpoint}`, {
+          method: "POST",
+          body: JSON.stringify(body)
+        });
+        const data = await res.json();
+        const redirectUrl = data?.url ?? data?.data?.url;
+        if (redirectUrl) {
+          window.location.assign(redirectUrl);
+        } else {
+          throw new Error(`signInWithProvider: no redirect URL returned for provider "${provider}"`);
+        }
+      },
+      /**
+       * Refresh an authentication token
+       * Note: better-auth handles token refresh automatically via /get-session
+       * @param _refreshToken - Not used (better-auth handles refresh automatically)
+       */
+      refreshToken: async (_refreshToken) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/get-session`, {
+          method: "GET"
+        });
         const data = await res.json();
         if (data.data?.token) {
           this.token = data.data.token;
@@ -652,54 +1371,262 @@ var ObjectStackClient = class {
         return data;
       },
       /**
-       * Logout current user
-       * Uses better-auth endpoint: POST /sign-out
+       * Probe the framework-only `/auth/bootstrap-status` endpoint to determine
+       * whether the very first owner has been provisioned. The Account portal's
+       * `/setup` route uses this to decide whether to render the bootstrap form
+       * or bounce the user straight to `/login`.
+       */
+      bootstrapStatus: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/bootstrap-status`);
+        const data = await res.json();
+        const payload = data?.data ?? data;
+        return { hasOwner: !!payload?.hasOwner };
+      },
+      /**
+       * Update the current user's profile.
+       *
+       * better-auth: POST /update-user — accepts `{ name?, image?, ... }`
+       * (any custom user fields configured on the server). Returns the
+       * updated user.
+       */
+      updateUser: async (data) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/update-user`, {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+        return res.json();
+      },
+      /**
+       * Change the current user's password (email/password accounts only).
+       *
+       * better-auth: POST /change-password.
+       * Set `revokeOtherSessions: true` to invalidate every other session
+       * after the change.
+       */
+      changePassword: async (req) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/change-password`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
+      },
+      /**
+       * Begin a change-email flow. better-auth sends a verification mail to
+       * the new address; the change only takes effect after the user clicks
+       * the link.
+       *
+       * better-auth: POST /change-email — `{ newEmail, callbackURL? }`.
+       */
+      changeEmail: async (req) => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/change-email`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
+      },
+      /**
+       * Re-send the email-verification link to the current user (or any
+       * address when called as an admin). better-auth: POST /send-verification-email.
        */
-      logout: async () => {
+      sendVerificationEmail: async (req) => {
         const route = this.getRoute("auth");
-        await this.fetch(`${this.baseUrl}${route}/sign-out`, { method: "POST" });
-        this.token = void 0;
+        const res = await this.fetch(`${this.baseUrl}${route}/send-verification-email`, {
+          method: "POST",
+          body: JSON.stringify(req)
+        });
+        return res.json();
       },
       /**
-       * Get current user session
-       * Uses better-auth endpoint: GET /get-session
+       * Verify an email-verification token (the link target).
+       *
+       * better-auth: GET /verify-email?token=…&callbackURL=…
        */
-      me: async () => {
+      verifyEmail: async (params) => {
         const route = this.getRoute("auth");
-        const res = await this.fetch(`${this.baseUrl}${route}/get-session`);
+        const url = new URL(`${this.baseUrl}${route}/verify-email`);
+        url.searchParams.set("token", params.token);
+        if (params.callbackURL) url.searchParams.set("callbackURL", params.callbackURL);
+        const res = await this.fetch(url.toString());
         return res.json();
       },
       /**
-       * Register a new user account
-       * Uses better-auth endpoint: POST /sign-up/email
+       * Permanently delete the current user. better-auth supports two flows:
+       *
+       *   1. With a fresh-session password challenge: POST `{ password }`.
+       *   2. With an emailed deletion-confirmation token: POST `{ token }`,
+       *      typically following an out-of-band confirmation step.
+       *
+       * Server policy decides which is required; pass whichever you have.
        */
-      register: async (request) => {
+      deleteUser: async (req) => {
         const route = this.getRoute("auth");
-        const res = await this.fetch(`${this.baseUrl}${route}/sign-up/email`, {
+        const res = await this.fetch(`${this.baseUrl}${route}/delete-user`, {
           method: "POST",
-          body: JSON.stringify(request)
+          body: JSON.stringify(req)
         });
-        const data = await res.json();
-        if (data.data?.token) {
-          this.token = data.data.token;
+        this.token = void 0;
+        return res.json();
+      },
+      /**
+       * Active-session management. Wraps better-auth's session endpoints so
+       * the Account portal's `/account/sessions` page can list every device
+       * the user is signed in from and revoke them individually or in bulk.
+       */
+      sessions: {
+        /** better-auth: GET /list-sessions — returns the current user's sessions. */
+        list: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/list-sessions`);
+          const data = await res.json();
+          const sessions = Array.isArray(data) ? data : data?.data ?? data?.sessions ?? [];
+          return { sessions };
+        },
+        /** better-auth: POST /revoke-session — revoke a single session by token. */
+        revoke: async (token) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/revoke-session`, {
+            method: "POST",
+            body: JSON.stringify({ token })
+          });
+          return res.json();
+        },
+        /** better-auth: POST /revoke-other-sessions — keep current, kill the rest. */
+        revokeOthers: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/revoke-other-sessions`, {
+            method: "POST",
+            body: "{}"
+          });
+          return res.json();
+        },
+        /** better-auth: POST /revoke-sessions — kill every session for this user. */
+        revokeAll: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/revoke-sessions`, {
+            method: "POST",
+            body: "{}"
+          });
+          this.token = void 0;
+          return res.json();
         }
-        return data;
       },
       /**
-       * Refresh an authentication token
-       * Note: better-auth handles token refresh automatically via /get-session
-       * @param _refreshToken - Not used (better-auth handles refresh automatically)
+       * Two-factor authentication (TOTP + backup codes). Requires the
+       * `twoFactor` plugin to be enabled on the server (see
+       * `plugin-auth` config). Endpoints live under `/two-factor/*`.
        */
-      refreshToken: async (_refreshToken) => {
-        const route = this.getRoute("auth");
-        const res = await this.fetch(`${this.baseUrl}${route}/get-session`, {
-          method: "GET"
-        });
-        const data = await res.json();
-        if (data.data?.token) {
-          this.token = data.data.token;
+      twoFactor: {
+        /**
+         * Start enrolment. Server returns a TOTP URI (`otpauth://...`) which
+         * the UI renders as a QR code; the user then calls `verifyTotp` to
+         * confirm and finish enabling.
+         */
+        enable: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/two-factor/enable`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          const data = await res.json();
+          return data?.data ?? data;
+        },
+        /**
+         * Confirm a TOTP code — used to finalise enrolment after `enable()`
+         * or to step up an existing 2FA-enabled session. `trustDevice` (when
+         * supported by the server config) suppresses the 2FA challenge on
+         * this browser for the configured trust period.
+         */
+        verifyTotp: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/two-factor/verify-totp`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        },
+        /** Disable 2FA for the current user. Requires the password again. */
+        disable: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/two-factor/disable`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        },
+        /**
+         * Issue a fresh set of backup codes (invalidating any previous set).
+         * Display them once — the server only stores hashes.
+         */
+        generateBackupCodes: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/two-factor/generate-backup-codes`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          const data = await res.json();
+          return data?.data ?? data;
+        },
+        /**
+         * Verify a 2FA backup code in lieu of a TOTP. Useful as a recovery
+         * affordance when the user has lost their authenticator app.
+         */
+        verifyBackupCode: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/two-factor/verify-backup-code`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        }
+      },
+      /**
+       * Linked credentials — i.e. the rows in better-auth's `account` table
+       * (one per provider × user). Lets the user see and unlink their social
+       * / OIDC connections from the Account portal.
+       */
+      accounts: {
+        /** better-auth: GET /list-accounts */
+        list: async () => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/list-accounts`);
+          const data = await res.json();
+          const accounts = Array.isArray(data) ? data : data?.data ?? data?.accounts ?? [];
+          return { accounts };
+        },
+        /**
+         * Unlink a provider connection.
+         * better-auth: POST /unlink-account — `{ providerId, accountId? }`.
+         * `accountId` is required when the user has more than one account
+         * for the same provider.
+         */
+        unlink: async (req) => {
+          const route = this.getRoute("auth");
+          const res = await this.fetch(`${this.baseUrl}${route}/unlink-account`, {
+            method: "POST",
+            body: JSON.stringify(req)
+          });
+          return res.json();
+        },
+        /**
+         * Link an additional social provider to the current user.
+         * better-auth: POST /link-social — `{ provider, callbackURL }`. The
+         * server returns a redirect URL; the caller should `window.location`
+         * to it (mirroring `signInWithProvider`).
+         */
+        linkSocial: async (req) => {
+          const route = this.getRoute("auth");
+          const callbackURL = req.callbackURL ?? (typeof window !== "undefined" ? window.location.href : void 0);
+          const res = await this.fetch(`${this.baseUrl}${route}/link-social`, {
+            method: "POST",
+            body: JSON.stringify({ provider: req.provider, callbackURL })
+          });
+          const data = await res.json();
+          return data?.data ?? data;
         }
-        return data;
       }
     };
     /**
@@ -906,6 +1833,46 @@ var ObjectStackClient = class {
           const res = await this.fetch(`${this.baseUrl}${route}/${flowName}/runs/${runId}`);
           return this.unwrapResponse(res);
         }
+      },
+      /**
+       * Flat aliases mirroring the ScopedProjectClient.automation surface so
+       * Studio (and other consumers) can use the same call shape regardless of
+       * whether they hold a scoped or unscoped client.
+       */
+      /** Alias for `automation.get` — fetch a flow definition by name. */
+      getFlow: async (name) => {
+        const route = this.getRoute("automation");
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(name)}`);
+        return this.unwrapResponse(res);
+      },
+      /** Execute (trigger) a flow with an execution context. */
+      execute: async (name, ctx) => {
+        const route = this.getRoute("automation");
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(name)}/trigger`, {
+          method: "POST",
+          body: JSON.stringify(ctx ?? {})
+        });
+        return this.unwrapResponse(res);
+      },
+      /** Alias for `automation.runs.list`. */
+      listRuns: async (flowName, opts) => {
+        const route = this.getRoute("automation");
+        const params = new URLSearchParams();
+        if (opts?.limit != null) params.set("limit", String(opts.limit));
+        if (opts?.cursor) params.set("cursor", opts.cursor);
+        const qs = params.toString();
+        const res = await this.fetch(
+          `${this.baseUrl}${route}/${encodeURIComponent(flowName)}/runs${qs ? `?${qs}` : ""}`
+        );
+        return this.unwrapResponse(res);
+      },
+      /** Alias for `automation.runs.get`. */
+      getRun: async (flowName, runId) => {
+        const route = this.getRoute("automation");
+        const res = await this.fetch(
+          `${this.baseUrl}${route}/${encodeURIComponent(flowName)}/runs/${encodeURIComponent(runId)}`
+        );
+        return this.unwrapResponse(res);
       }
     };
     /**
@@ -1596,6 +2563,7 @@ var ObjectStackClient = class {
     };
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.token = config.token;
+    this.projectId = config.projectId;
     this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
     this.logger = config.logger || createLogger({
       level: config.debug ? "debug" : "info",
@@ -1612,6 +2580,18 @@ var ObjectStackClient = class {
     try {
       let data;
       try {
+        const discoveryUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug("Probing protocol-standard discovery endpoint", { url: discoveryUrl });
+        const res = await this.fetchImpl(discoveryUrl);
+        if (res.ok) {
+          const body = await res.json();
+          data = body.data || body;
+          this.logger.debug("Discovered via /api/v1/discovery");
+        }
+      } catch (e) {
+        this.logger.debug("Protocol-standard discovery probe failed", { error: e.message });
+      }
+      if (!data) {
         let wellKnownUrl;
         try {
           const url = new URL(this.baseUrl);
@@ -1619,22 +2599,10 @@ var ObjectStackClient = class {
         } catch {
           wellKnownUrl = "/.well-known/objectstack";
         }
-        this.logger.debug("Probing .well-known discovery", { url: wellKnownUrl });
+        this.logger.debug("Falling back to .well-known discovery", { url: wellKnownUrl });
         const res = await this.fetchImpl(wellKnownUrl);
-        if (res.ok) {
-          const body = await res.json();
-          data = body.data || body;
-          this.logger.debug("Discovered via .well-known");
-        }
-      } catch (e) {
-        this.logger.debug("Standard discovery probe failed", { error: e.message });
-      }
-      if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
-        this.logger.debug("Falling back to standard discovery endpoint", { url: fallbackUrl });
-        const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
-          throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
+          throw new Error(`Failed to connect to ${wellKnownUrl}: ${res.statusText}`);
         }
         const body = await res.json();
         data = body.data || body;
@@ -1672,6 +2640,64 @@ var ObjectStackClient = class {
     }
     return result;
   }
+  /**
+   * Project-scoped client factory.
+   *
+   * Returns a thin wrapper around the data / meta / packages namespaces that
+   * prefixes every request with `/api/v1/projects/:projectId/...`. Use this
+   * when the server has `enableProjectScoping: true` in its REST API config.
+   *
+   * Backward compatibility: `client.data.*`, `client.meta.*`, and
+   * `client.packages.*` continue to work unchanged; they hit unscoped routes
+   * and rely on hostname / `X-Project-Id` header / session resolution.
+   *
+   * @example
+   * ```ts
+   * const scoped = client.project('00000000-0000-0000-0000-000000000001');
+   * const tasks = await scoped.data.find('task', { top: 10 });
+   * const objects = await scoped.meta.getItems('object');
+   * ```
+   */
+  project(projectId) {
+    if (!projectId) {
+      throw new Error("[ObjectStack] project(id): projectId is required");
+    }
+    return new ScopedProjectClient(this, projectId);
+  }
+  // ── Internal accessors exposed to ScopedProjectClient ────────────────
+  // The scoped client lives in the same module so using module-level access
+  // works; TypeScript requires these to be accessible, so we expose them via
+  // small protected getters that keep the public surface unchanged.
+  /** @internal */
+  _baseUrl() {
+    return this.baseUrl;
+  }
+  /** @internal */
+  _fetch(url, init) {
+    return this.fetch(url, init);
+  }
+  /** @internal */
+  _unwrap(res) {
+    return this.unwrapResponse(res);
+  }
+  /** @internal */
+  _isFilterAST(v) {
+    return this.isFilterAST(v);
+  }
+  /**
+   * Update the active project id used for subsequent requests.
+   * Pass `undefined` to clear (falls back to the session default).
+   */
+  setProjectId(projectId) {
+    this.projectId = projectId;
+    this.logger.debug("Active project changed", { projectId });
+  }
+  /**
+   * Current active project id (if set).
+   */
+  getProjectId() {
+    return this.projectId;
+  }
   /**
    * Event Subscription API
    * Provides real-time event subscriptions for metadata and data changes
@@ -1712,6 +2738,9 @@ var ObjectStackClient = class {
     if (this.token) {
       headers["Authorization"] = `Bearer ${this.token}`;
     }
+    if (this.projectId) {
+      headers["X-Project-Id"] = this.projectId;
+    }
     const res = await this.fetchImpl(url, { ...options, headers });
     this.logger.debug("HTTP response", {
       method: options.method || "GET",
@@ -1778,11 +2807,246 @@ var ObjectStackClient = class {
     return routeMap[type] || `/api/v1/${type}`;
   }
 };
+var ScopedProjectClient = class {
+  constructor(parent, projectId) {
+    /**
+     * Metadata operations scoped to this project.
+     */
+    this.meta = {
+      getTypes: async () => {
+        const res = await this.parent._fetch(this.url("/meta"));
+        return this.parent._unwrap(res);
+      },
+      getItems: async (type, options) => {
+        const params = new URLSearchParams();
+        if (options?.packageId) params.set("package", options.packageId);
+        const qs = params.toString();
+        const res = await this.parent._fetch(this.url(`/meta/${type}${qs ? `?${qs}` : ""}`));
+        return this.parent._unwrap(res);
+      },
+      getItem: async (type, name, options) => {
+        const params = new URLSearchParams();
+        if (options?.packageId) params.set("package", options.packageId);
+        const qs = params.toString();
+        const res = await this.parent._fetch(this.url(`/meta/${type}/${name}${qs ? `?${qs}` : ""}`));
+        return this.parent._unwrap(res);
+      },
+      saveItem: async (type, name, item) => {
+        const res = await this.parent._fetch(this.url(`/meta/${type}/${name}`), {
+          method: "PUT",
+          body: JSON.stringify(item)
+        });
+        return this.parent._unwrap(res);
+      },
+      deleteItem: async (type, name) => {
+        const res = await this.parent._fetch(this.url(`/meta/${encodeURIComponent(type)}/${encodeURIComponent(name)}`), {
+          method: "DELETE"
+        });
+        return this.parent._unwrap(res);
+      }
+    };
+    /**
+     * Data operations scoped to this project.
+     *
+     * Mirrors the query / find / get / create / update / delete / batch
+     * surface on {@link ObjectStackClient}. URL construction differs only
+     * in the prefix — query parameter serialization is identical.
+     */
+    this.data = {
+      query: async (object, query) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/query`), {
+          method: "POST",
+          body: JSON.stringify(query)
+        });
+        return this.parent._unwrap(res);
+      },
+      find: async (object, options = {}) => {
+        const queryParams = new URLSearchParams();
+        const v2 = options;
+        const normalizedOptions = {};
+        if ("where" in options || "fields" in options || "orderBy" in options || "offset" in options) {
+          if (v2.where) normalizedOptions.filter = v2.where;
+          if (v2.fields) normalizedOptions.select = v2.fields;
+          if (v2.orderBy) normalizedOptions.sort = v2.orderBy;
+          if (v2.limit != null) normalizedOptions.top = v2.limit;
+          if (v2.offset != null) normalizedOptions.skip = v2.offset;
+          if (v2.aggregations) normalizedOptions.aggregations = v2.aggregations;
+          if (v2.groupBy) normalizedOptions.groupBy = v2.groupBy;
+        } else {
+          Object.assign(normalizedOptions, options);
+        }
+        if (normalizedOptions.top) queryParams.set("top", normalizedOptions.top.toString());
+        if (normalizedOptions.skip) queryParams.set("skip", normalizedOptions.skip.toString());
+        if (normalizedOptions.sort) {
+          if (Array.isArray(normalizedOptions.sort) && typeof normalizedOptions.sort[0] === "object") {
+            queryParams.set("sort", JSON.stringify(normalizedOptions.sort));
+          } else {
+            const sortVal = Array.isArray(normalizedOptions.sort) ? normalizedOptions.sort.join(",") : normalizedOptions.sort;
+            queryParams.set("sort", sortVal);
+          }
+        }
+        if (normalizedOptions.select) {
+          queryParams.set("select", normalizedOptions.select.join(","));
+        }
+        const filterValue = normalizedOptions.filter ?? normalizedOptions.filters;
+        if (filterValue) {
+          if (this.parent._isFilterAST(filterValue) || Array.isArray(filterValue)) {
+            queryParams.set("filter", JSON.stringify(filterValue));
+          } else if (typeof filterValue === "object" && filterValue !== null) {
+            Object.entries(filterValue).forEach(([k, v]) => {
+              if (v !== void 0 && v !== null) {
+                queryParams.append(k, String(v));
+              }
+            });
+          }
+        }
+        if (normalizedOptions.aggregations) {
+          queryParams.set("aggregations", JSON.stringify(normalizedOptions.aggregations));
+        }
+        if (normalizedOptions.groupBy) {
+          queryParams.set("groupBy", normalizedOptions.groupBy.join(","));
+        }
+        const qs = queryParams.toString();
+        const res = await this.parent._fetch(this.url(`/data/${object}${qs ? `?${qs}` : ""}`));
+        return this.parent._unwrap(res);
+      },
+      get: async (object, id) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/${id}`));
+        return this.parent._unwrap(res);
+      },
+      create: async (object, data) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}`), {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+        return this.parent._unwrap(res);
+      },
+      createMany: async (object, data) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/createMany`), {
+          method: "POST",
+          body: JSON.stringify(data)
+        });
+        return this.parent._unwrap(res);
+      },
+      update: async (object, id, data) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/${id}`), {
+          method: "PATCH",
+          body: JSON.stringify(data)
+        });
+        return this.parent._unwrap(res);
+      },
+      batch: async (object, request) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/batch`), {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return this.parent._unwrap(res);
+      },
+      updateMany: async (object, records, options) => {
+        const request = { records, options };
+        const res = await this.parent._fetch(this.url(`/data/${object}/updateMany`), {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return this.parent._unwrap(res);
+      },
+      delete: async (object, id) => {
+        const res = await this.parent._fetch(this.url(`/data/${object}/${id}`), {
+          method: "DELETE"
+        });
+        return this.parent._unwrap(res);
+      },
+      deleteMany: async (object, ids, options) => {
+        const request = { ids, options };
+        const res = await this.parent._fetch(this.url(`/data/${object}/deleteMany`), {
+          method: "POST",
+          body: JSON.stringify(request)
+        });
+        return this.parent._unwrap(res);
+      }
+    };
+    /**
+     * Package management scoped to this project.
+     * Only the read-path is exposed here — publish / delete remain on the
+     * global `client.packages` namespace for now, pending dedicated per-project
+     * package tests.
+     */
+    this.packages = {
+      list: async () => {
+        const res = await this.parent._fetch(this.url("/packages"));
+        return this.parent._unwrap(res);
+      },
+      get: async (id, version) => {
+        const qs = version ? `?version=${encodeURIComponent(version)}` : "";
+        const res = await this.parent._fetch(this.url(`/packages/${encodeURIComponent(id)}${qs}`));
+        return this.parent._unwrap(res);
+      }
+    };
+    /**
+     * Automation (Flow) operations scoped to this project.
+     *
+     * Thin wrapper around the dispatcher's automation routes, mounted under
+     * `/api/v1/projects/:projectId/automation/...`. Surface mirrors the methods
+     * needed by Studio's Flow viewer: read flow definition, execute (trigger),
+     * list runs, fetch a single run.
+     */
+    this.automation = {
+      /** Fetch a flow definition by name. */
+      getFlow: async (name) => {
+        const res = await this.parent._fetch(this.url(`/automation/${encodeURIComponent(name)}`));
+        return this.parent._unwrap(res);
+      },
+      /**
+       * Execute (trigger) a flow by name. The request body is forwarded as the
+       * automation execution context (e.g. `{ params, trigger }`).
+       */
+      execute: async (name, ctx) => {
+        const res = await this.parent._fetch(this.url(`/automation/${encodeURIComponent(name)}/trigger`), {
+          method: "POST",
+          body: JSON.stringify(ctx ?? {})
+        });
+        return this.parent._unwrap(res);
+      },
+      /** List recent runs for a flow. */
+      listRuns: async (flowName, opts) => {
+        const params = new URLSearchParams();
+        if (opts?.limit != null) params.set("limit", String(opts.limit));
+        if (opts?.cursor) params.set("cursor", opts.cursor);
+        const qs = params.toString();
+        const res = await this.parent._fetch(
+          this.url(`/automation/${encodeURIComponent(flowName)}/runs${qs ? `?${qs}` : ""}`)
+        );
+        return this.parent._unwrap(res);
+      },
+      /** Fetch a single run (with step log) for a flow. */
+      getRun: async (flowName, runId) => {
+        const res = await this.parent._fetch(
+          this.url(`/automation/${encodeURIComponent(flowName)}/runs/${encodeURIComponent(runId)}`)
+        );
+        return this.parent._unwrap(res);
+      }
+    };
+    this.parent = parent;
+    this.projectId = projectId;
+  }
+  /** The projectId this client is scoped to. */
+  getProjectId() {
+    return this.projectId;
+  }
+  /** Prefix segment inserted between the baseUrl and the resource path. */
+  scope() {
+    return `/api/v1/projects/${encodeURIComponent(this.projectId)}`;
+  }
+  url(suffix) {
+    return `${this.parent._baseUrl()}${this.scope()}${suffix}`;
+  }
+};
 export {
   FilterBuilder,
   ObjectStackClient,
   QueryBuilder,
   RealtimeAPI,
+  ScopedProjectClient,
   createFilter,
   createQuery
 };