@objectstack/client 4.0.4 → 4.1.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-import { MetadataEvent, DataEvent, ApiRoutes, GetDiscoveryResponse, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions, StandardErrorCode, ErrorCategory } from '@objectstack/spec/api';
+import { MetadataEvent, DataEvent, ApiRoutes, GetDiscoveryResponse, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, StandardErrorCode, ErrorCategory } from '@objectstack/spec/api';
 export { AddReactionResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, AuthFeaturesConfig, AuthProviderInfo, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateFeedItemResponse, CreateViewResponse, DeleteFeedItemResponse, DeleteManyRequest, DeleteViewResponse, EmailPasswordConfigPublic, ErrorCategory, GetAuthConfigResponse, GetChangelogResponse, GetDiscoveryResponse, GetEffectivePermissionsResponse, GetFeedResponse, GetFieldLabelsResponse, GetLocalesResponse, GetMetaItemsResponse, GetMetaTypesResponse, GetObjectPermissionsResponse, GetPresenceResponse, GetTranslationsResponse, GetViewResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, ListNotificationsResponse, ListViewsResponse, MetadataCacheRequest, MetadataCacheResponse, PinFeedItemResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RefreshTokenRequest, RegisterDeviceRequest, RegisterDeviceResponse, RegisterRequest, RemoveReactionResponse, SearchFeedResponse, StandardErrorCode, StarFeedItemResponse, SubscribeResponse, UnpinFeedItemResponse, UnstarFeedItemResponse, UnsubscribeResponse, UpdateFeedItemResponse, UpdateManyRequest, UpdateViewResponse, WellKnownCapabilities, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
-import { Logger } from '@objectstack/core';
+import { Logger } from '@objectstack/core/logger';
 import { RealtimeEventPayload } from '@objectstack/spec/contracts';
 
 /**
@@ -263,6 +263,14 @@ interface ClientConfig {
      * Enable debug logging
      */
     debug?: boolean;
+    /**
+     * Active project id (UUID of `sys_project`). When present, the
+     * client injects an `X-Project-Id` header on every request so the
+     * server's tenant router can resolve the physical data-plane database.
+     *
+     * @see docs/adr/0002-project-database-isolation.md
+     */
+    projectId?: string;
 }
 /**
  * Discovery Result
@@ -366,6 +374,7 @@ interface StandardError {
 declare class ObjectStackClient {
     private baseUrl;
     private token?;
+    private projectId?;
     private fetchImpl;
     private discoveryInfo?;
     private logger;
@@ -377,7 +386,7 @@ declare class ObjectStackClient {
     connect(): Promise<{
         version: string;
         name?: string | undefined;
-        environment?: "development" | "production" | "sandbox" | undefined;
+        environment?: "production" | "sandbox" | "development" | undefined;
         routes?: {
             data: string;
             metadata: string;
@@ -403,7 +412,7 @@ declare class ObjectStackClient {
         } | undefined;
         services?: Record<string, {
             enabled: boolean;
-            status: "degraded" | "stub" | "available" | "registered" | "unavailable";
+            status: "available" | "registered" | "unavailable" | "degraded" | "stub";
             handlerReady?: boolean | undefined;
             route?: string | undefined;
             provider?: string | undefined;
@@ -564,6 +573,653 @@ declare class ObjectStackClient {
             message?: string;
         }>;
     };
+    /**
+     * 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
+     */
+    projects: {
+        /**
+         * List environments visible to the current session. Optionally filter
+         * by organization (control-plane query — not routed through a data-plane DB).
+         */
+        list: (filters?: {
+            organization_id?: string;
+            env_type?: string;
+            status?: string;
+        }) => Promise<{
+            projects: any[];
+            total: number;
+        }>;
+        /**
+         * Get a single project (joined with its database and membership row).
+         */
+        get: (id: string) => Promise<{
+            project: any;
+            database?: any;
+            credential?: any;
+            membership?: any;
+            organization?: any;
+        }>;
+        /**
+         * Provision a new project. Delegates to
+         * `ProjectProvisioningService.provisionProject` on the server.
+         */
+        create: (req: {
+            organization_id: string;
+            slug?: string;
+            display_name: string;
+            env_type?: string;
+            project_type?: string;
+            plan?: string;
+            region?: string;
+            driver?: string;
+            is_default?: boolean;
+            is_system?: boolean;
+            storage_limit_mb?: number;
+            clone_from_project_id?: string;
+            template_id?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<{
+            project: any;
+            database: any;
+        }>;
+        /**
+         * Update a project (display_name, plan, status, is_default, metadata).
+         */
+        update: (id: string, patch: Record<string, unknown>) => Promise<{
+            project: any;
+        }>;
+        /**
+         * 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: (id: string, opts?: {
+            force?: boolean;
+        }) => Promise<{
+            deleted: boolean;
+            projectId: string;
+            warnings: string[];
+        }>;
+        /**
+         * 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: (id: string) => Promise<{
+            project: any;
+            sessionUpdated: boolean;
+        }>;
+        /**
+         * Rotate the active database credential for this project.
+         */
+        rotateCredential: (id: string, plaintext: string) => Promise<{
+            credential: any;
+        }>;
+        /**
+         * Update the hostname bound to this project. Validates format and
+         * uniqueness server-side; invalidates the dispatcher's routing cache.
+         */
+        updateHostname: (id: string, hostname: string) => Promise<{
+            project: any;
+        }>;
+        /**
+         * Update the visibility of this project ('private' | 'public').
+         * `private` (default) hides the project from /pub/v1 enumeration but
+         * still allows anonymous artifact downloads when the URL includes an
+         * exact `?commit=<id>` (share-by-link). `public` lists the project and
+         * freely exposes all revisions.
+         */
+        updateVisibility: (id: string, visibility: "private" | "public") => Promise<{
+            project: any;
+        }>;
+        /**
+         * List published artifact revisions for a project. Each revision has
+         * an immutable commitId (content-addressable) and storage_key.
+         * Optional `branch` filter narrows to a single logical branch
+         * (default branch `main` also matches rows with NULL `branch`).
+         */
+        listRevisions: (id: string, opts?: {
+            limit?: number;
+            cursor?: string;
+            branch?: string;
+        }) => Promise<{
+            items: Array<{
+                commitId: string;
+                checksum: string;
+                storageKey: string;
+                sizeBytes: number;
+                builtAt: string;
+                publishedAt: string;
+                publishedBy: string | null;
+                note: string | null;
+                isCurrent: boolean;
+                branch: string;
+                isBranchHead: boolean;
+            }>;
+            nextCursor: string | null;
+            branch: string | null;
+        }>;
+        /**
+         * List logical branches for a project. Each branch has a head commit
+         * (latest published revision on that branch) and a count of revisions.
+         * Branches without a head row (e.g. all rows demoted) are omitted.
+         */
+        listBranches: (id: string) => Promise<{
+            projectId: string;
+            branches: Array<{
+                branch: string;
+                headCommitId: string;
+                headRevisionId: string;
+                revisionCount: number;
+                headPublishedAt: string | null;
+                headNote: string | null;
+                isCurrent: boolean;
+            }>;
+        }>;
+        /**
+         * Rename a branch. Updates every revision row in `from` to `to`.
+         * 409 if `to` already has rows.
+         */
+        renameBranch: (id: string, from: string, to: string) => Promise<{
+            projectId: string;
+            from: string;
+            to: string;
+            renamed: number;
+        }>;
+        /**
+         * Delete (demote) a branch. Soft-removal — clears `is_branch_head` on
+         * every row in this branch; the revisions themselves remain. The
+         * `main` branch and any branch carrying the active revision cannot be
+         * deleted.
+         */
+        deleteBranch: (id: string, name: string) => Promise<{
+            projectId: string;
+            branch: string;
+            demoted: number;
+            totalRevisions: number;
+        }>;
+        /**
+         * Activate (rollback to) a previously-published revision by commit id.
+         * Marks the target revision is_current=true and demotes the prior one.
+         */
+        activateRevision: (id: string, commitId: string) => Promise<{
+            projectId: string;
+            commitId: string;
+            activated: boolean;
+            previousCommitId: string | null;
+        }>;
+        /**
+         * 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: (id: string) => Promise<{
+            project: any;
+        }>;
+        /**
+         * List members of a project (per-project RBAC).
+         */
+        listMembers: (id: string) => Promise<{
+            members: any[];
+        }>;
+        /**
+         * Invite a member to a project. Caller must be `owner` or `admin`.
+         * Pass either `email` (resolved against the user table) or `user_id`.
+         * Returns `{ member, alreadyMember }` — `alreadyMember=true` means the
+         * row already existed; the call is idempotent.
+         */
+        addMember: (id: string, payload: {
+            email?: string;
+            user_id?: string;
+            role?: "owner" | "admin" | "member" | "viewer";
+        }) => Promise<{
+            member: any;
+            alreadyMember: boolean;
+        }>;
+        /**
+         * Update a member's role. Caller must be `owner` or `admin`. Demoting
+         * the last `owner` returns 409.
+         */
+        updateMemberRole: (id: string, memberId: string, role: "owner" | "admin" | "member" | "viewer") => Promise<{
+            member: any;
+        }>;
+        /**
+         * Remove a member. Owners/admins may remove anyone; non-privileged
+         * users may only remove themselves. Removing the last `owner` returns 409.
+         */
+        removeMember: (id: string, memberId: string) => Promise<{
+            removed: boolean;
+            memberId: string;
+        }>;
+        /**
+         * 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: () => Promise<{
+            drivers: Array<{
+                name: string;
+                driverId: string;
+            }>;
+            total: number;
+        }>;
+        /**
+         * List available project templates. Templates are seeded into the project
+         * database once at provisioning time when `template_id` is supplied.
+         */
+        listTemplates: () => Promise<{
+            templates: Array<{
+                id: string;
+                label: string;
+                description: string;
+                category?: string;
+            }>;
+            total: number;
+        }>;
+        /**
+         * 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: (envId: string) => Promise<{
+                packages: any[];
+                total: number;
+            }>;
+            /** Install a package into the project. */
+            install: (envId: string, body: {
+                packageId: string;
+                version?: string;
+                settings?: Record<string, unknown>;
+                enableOnInstall?: boolean;
+            }) => Promise<{
+                package: any;
+            }>;
+            /** Get a single installation record. */
+            get: (envId: string, pkgId: string) => Promise<{
+                package: any;
+            }>;
+            /** Enable a previously disabled package. */
+            enable: (envId: string, pkgId: string) => Promise<{
+                package: any;
+            }>;
+            /** Disable an installed package (metadata will not be loaded). */
+            disable: (envId: string, pkgId: string) => Promise<{
+                package: any;
+            }>;
+            /** Uninstall a package from the project. Forbidden for scope=platform packages. */
+            uninstall: (envId: string, pkgId: string) => Promise<{
+                id: string;
+                success: boolean;
+            }>;
+            /** Upgrade an installed package to a newer version. */
+            upgrade: (envId: string, pkgId: string, targetVersion?: string) => Promise<{
+                package: any;
+            }>;
+        };
+    };
+    /**
+     * 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: string): ScopedProjectClient;
+    /** @internal */
+    _baseUrl(): string;
+    /** @internal */
+    _fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** @internal */
+    _unwrap<T>(res: Response): Promise<T>;
+    /** @internal */
+    _isFilterAST(v: unknown): boolean;
+    /**
+     * 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.
+     */
+    organizations: {
+        /**
+         * List organizations the current user belongs to.
+         * GET /api/v1/auth/organization/list
+         */
+        list: () => Promise<{
+            organizations: Array<{
+                id: string;
+                name: string;
+                slug?: string;
+                logo?: string;
+                metadata?: any;
+            }>;
+        }>;
+        /**
+         * Create a new organization.
+         * POST /api/v1/auth/organization/create
+         */
+        create: (req: {
+            name: string;
+            slug?: string;
+            logo?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<any>;
+        /**
+         * 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: (organizationId: string, data: {
+            name?: string;
+            slug?: string;
+            logo?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<any>;
+        /**
+         * 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: (organizationId: string) => Promise<any>;
+        /**
+         * Get full organization detail (members, invitations, teams).
+         * GET /api/v1/auth/organization/get-full-organization?organizationId=...
+         */
+        get: (organizationId: string) => Promise<any>;
+        /**
+         * List members of an organization.
+         */
+        listMembers: (organizationId: string) => Promise<any>;
+        /**
+         * Invite a user to the organization.
+         */
+        invite: (req: {
+            email: string;
+            role?: string;
+            organizationId?: string;
+        }) => Promise<any>;
+        /**
+         * Leave the given organization.
+         */
+        leave: (organizationId: string) => Promise<any>;
+        /**
+         * 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: (organizationId: string) => Promise<any>;
+        /**
+         * 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: (organizationId: string, params: {
+            memberIdOrEmail: string;
+        }) => Promise<any>;
+        /**
+         * 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: (organizationId: string, params: {
+            memberId: string;
+            role: string;
+        }) => Promise<any>;
+        /**
+         * 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: (organizationId: string) => Promise<any>;
+        /**
+         * 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: (organizationId: string) => Promise<{
+                invitations: Array<{
+                    id: string;
+                    email: string;
+                    role: string;
+                    status: "pending" | "accepted" | "rejected" | "canceled";
+                    organizationId: string;
+                    inviterId: string;
+                    expiresAt: string;
+                    teamId?: string | null;
+                }>;
+            }>;
+            /**
+             * 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: () => Promise<{
+                invitations: Array<{
+                    id: string;
+                    email: string;
+                    role: string;
+                    status: string;
+                    organizationId: string;
+                    inviterId: string;
+                    expiresAt: string;
+                }>;
+            }>;
+            /** better-auth: POST /organization/cancel-invitation */
+            cancel: (invitationId: string) => Promise<any>;
+            /** better-auth: POST /organization/accept-invitation */
+            accept: (invitationId: string) => Promise<any>;
+            /** better-auth: POST /organization/reject-invitation */
+            reject: (invitationId: string) => Promise<any>;
+            /**
+             * "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: (invitation: {
+                id?: string;
+                email: string;
+                role?: string;
+                organizationId: string;
+                teamId?: string | null;
+            }) => Promise<any>;
+        };
+        /**
+         * 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: (organizationId: string) => Promise<{
+                teams: Array<{
+                    id: string;
+                    name: string;
+                    organizationId: string;
+                    createdAt?: string;
+                }>;
+            }>;
+            /** better-auth: POST /organization/create-team */
+            create: (req: {
+                name: string;
+                organizationId: string;
+            }) => Promise<any>;
+            /** better-auth: POST /organization/update-team */
+            update: (params: {
+                teamId: string;
+                data: {
+                    name?: string;
+                };
+            }) => Promise<any>;
+            /** better-auth: POST /organization/remove-team */
+            delete: (params: {
+                teamId: string;
+                organizationId?: string;
+            }) => Promise<any>;
+            /** better-auth: GET /organization/list-team-members?teamId=… */
+            listMembers: (teamId: string) => Promise<{
+                members: Array<{
+                    id: string;
+                    teamId: string;
+                    userId: string;
+                }>;
+            }>;
+            /** better-auth: POST /organization/add-team-member */
+            addMember: (params: {
+                teamId: string;
+                userId: string;
+            }) => Promise<any>;
+            /** better-auth: POST /organization/remove-team-member */
+            removeMember: (params: {
+                teamId: string;
+                userId: string;
+            }) => Promise<any>;
+        };
+    };
+    /**
+     * 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/*`.
+     */
+    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: (req: {
+                client_name?: string;
+                name?: string;
+                redirect_uris: string[];
+                token_endpoint_auth_method?: "none" | "client_secret_basic" | "client_secret_post";
+                grant_types?: string[];
+                response_types?: string[];
+                client_uri?: string;
+                logo_uri?: string;
+                scope?: string;
+                scopes?: string[];
+                contacts?: string[];
+                tos_uri?: string;
+                policy_uri?: string;
+                metadata?: Record<string, unknown>;
+            }) => Promise<any>;
+            /**
+             * Get a single OAuth application by its `client_id`.
+             * GET /api/v1/auth/oauth2/get-client?client_id=...
+             */
+            get: (clientId: string) => Promise<any>;
+            /**
+             * 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: (clientId: string) => Promise<any>;
+            /**
+             * 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: () => Promise<{
+                applications: Array<Record<string, any>>;
+            }>;
+            /**
+             * 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: (clientId: string) => Promise<any>;
+        };
+        /**
+         * 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: (req: {
+            accept: boolean;
+            scope?: string;
+            oauth_query?: string;
+        }) => Promise<any>;
+    };
+    /**
+     * Update the active project id used for subsequent requests.
+     * Pass `undefined` to clear (falls back to the session default).
+     */
+    setProjectId(projectId: string | undefined): void;
+    /**
+     * Current active project id (if set).
+     */
+    getProjectId(): string | undefined;
     /**
      * Authentication Services
      */
@@ -593,12 +1249,212 @@ declare class ObjectStackClient {
          * Uses better-auth endpoint: POST /sign-up/email
          */
         register: (request: RegisterRequest) => Promise<SessionResponse>;
+        /**
+         * 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: (provider: string, opts?: {
+            callbackURL?: string;
+            errorCallbackURL?: string;
+            type?: "social" | "oidc";
+        }) => Promise<void>;
         /**
          * Refresh an authentication token
          * Note: better-auth handles token refresh automatically via /get-session
          * @param _refreshToken - Not used (better-auth handles refresh automatically)
          */
         refreshToken: (_refreshToken: string) => Promise<SessionResponse>;
+        /**
+         * 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: () => Promise<{
+            hasOwner: boolean;
+        }>;
+        /**
+         * 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: (data: {
+            name?: string;
+            image?: string | null;
+            [key: string]: unknown;
+        }) => Promise<any>;
+        /**
+         * 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: (req: {
+            currentPassword: string;
+            newPassword: string;
+            revokeOtherSessions?: boolean;
+        }) => Promise<any>;
+        /**
+         * 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: (req: {
+            newEmail: string;
+            callbackURL?: string;
+        }) => Promise<any>;
+        /**
+         * Re-send the email-verification link to the current user (or any
+         * address when called as an admin). better-auth: POST /send-verification-email.
+         */
+        sendVerificationEmail: (req: {
+            email: string;
+            callbackURL?: string;
+        }) => Promise<any>;
+        /**
+         * Verify an email-verification token (the link target).
+         *
+         * better-auth: GET /verify-email?token=…&callbackURL=…
+         */
+        verifyEmail: (params: {
+            token: string;
+            callbackURL?: string;
+        }) => Promise<any>;
+        /**
+         * 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.
+         */
+        deleteUser: (req: {
+            password?: string;
+            token?: string;
+            callbackURL?: string;
+        }) => Promise<any>;
+        /**
+         * 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: () => Promise<{
+                sessions: Array<{
+                    id: string;
+                    token: string;
+                    userId: string;
+                    userAgent?: string;
+                    ipAddress?: string;
+                    createdAt: string;
+                    expiresAt: string;
+                }>;
+            }>;
+            /** better-auth: POST /revoke-session — revoke a single session by token. */
+            revoke: (token: string) => Promise<any>;
+            /** better-auth: POST /revoke-other-sessions — keep current, kill the rest. */
+            revokeOthers: () => Promise<any>;
+            /** better-auth: POST /revoke-sessions — kill every session for this user. */
+            revokeAll: () => Promise<any>;
+        };
+        /**
+         * 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/*`.
+         */
+        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: (req: {
+                password: string;
+            }) => Promise<{
+                totpURI?: string;
+                backupCodes?: string[];
+            }>;
+            /**
+             * 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: (req: {
+                code: string;
+                trustDevice?: boolean;
+            }) => Promise<any>;
+            /** Disable 2FA for the current user. Requires the password again. */
+            disable: (req: {
+                password: string;
+            }) => Promise<any>;
+            /**
+             * Issue a fresh set of backup codes (invalidating any previous set).
+             * Display them once — the server only stores hashes.
+             */
+            generateBackupCodes: (req: {
+                password: string;
+            }) => Promise<{
+                backupCodes: string[];
+            }>;
+            /**
+             * Verify a 2FA backup code in lieu of a TOTP. Useful as a recovery
+             * affordance when the user has lost their authenticator app.
+             */
+            verifyBackupCode: (req: {
+                code: string;
+            }) => Promise<any>;
+        };
+        /**
+         * 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: () => Promise<{
+                accounts: Array<{
+                    id: string;
+                    providerId: string;
+                    accountId: string;
+                    createdAt?: string;
+                    updatedAt?: string;
+                }>;
+            }>;
+            /**
+             * 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: (req: {
+                providerId: string;
+                accountId?: string;
+            }) => Promise<any>;
+            /**
+             * 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: (req: {
+                provider: string;
+                callbackURL?: string;
+            }) => Promise<{
+                url?: string;
+            }>;
+        };
     };
     /**
      * Storage Services
@@ -689,6 +1545,22 @@ declare class ObjectStackClient {
              */
             get: (flowName: string, runId: string) => Promise<any>;
         };
+        /**
+         * 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: <T = any>(name: string) => Promise<T>;
+        /** Execute (trigger) a flow with an execution context. */
+        execute: <T = any>(name: string, ctx?: Record<string, any>) => Promise<T>;
+        /** Alias for `automation.runs.list`. */
+        listRuns: <T = any>(flowName: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<T>;
+        /** Alias for `automation.runs.get`. */
+        getRun: <T = any>(flowName: string, runId: string) => Promise<T>;
     };
     /**
      * Event Subscription API
@@ -1018,5 +1890,107 @@ declare class ObjectStackClient {
      */
     private getRoute;
 }
+/**
+ * Project-scoped sub-client.
+ *
+ * Wraps an {@link ObjectStackClient} and prefixes every request with
+ * `/api/v1/projects/:projectId/...` so a single client instance can talk to
+ * multiple projects without mutating global state.
+ *
+ * The scoped client exposes the same shape as the `data`, `meta`, `batch`,
+ * and `packages` namespaces on `ObjectStackClient` — only the URL prefix
+ * differs. The server-side dual-mode route registration (see
+ * `packages/rest/src/rest-server.ts`) accepts both shapes when
+ * `projectResolution` is `'auto'` or `'optional'`.
+ */
+declare class ScopedProjectClient {
+    private readonly parent;
+    private readonly projectId;
+    constructor(parent: ObjectStackClient, projectId: string);
+    /** The projectId this client is scoped to. */
+    getProjectId(): string;
+    /** Prefix segment inserted between the baseUrl and the resource path. */
+    private scope;
+    private url;
+    /**
+     * Metadata operations scoped to this project.
+     */
+    meta: {
+        getTypes: () => Promise<GetMetaTypesResponse>;
+        getItems: (type: string, options?: {
+            packageId?: string;
+        }) => Promise<GetMetaItemsResponse>;
+        getItem: (type: string, name: string, options?: {
+            packageId?: string;
+        }) => Promise<unknown>;
+        saveItem: (type: string, name: string, item: any) => Promise<unknown>;
+        deleteItem: (type: string, name: string) => Promise<{
+            type: string;
+            name: string;
+            deleted: boolean;
+        }>;
+    };
+    /**
+     * 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.
+     */
+    data: {
+        query: <T = any>(object: string, query: Partial<QueryAST>) => Promise<PaginatedResult<T>>;
+        find: <T = any>(object: string, options?: QueryOptions | QueryOptionsV2) => Promise<PaginatedResult<T>>;
+        get: <T = any>(object: string, id: string) => Promise<GetDataResult<T>>;
+        create: <T = any>(object: string, data: Partial<T>) => Promise<CreateDataResult<T>>;
+        createMany: <T = any>(object: string, data: Partial<T>[]) => Promise<T[]>;
+        update: <T = any>(object: string, id: string, data: Partial<T>) => Promise<UpdateDataResult<T>>;
+        batch: (object: string, request: BatchUpdateRequest) => Promise<BatchUpdateResponse>;
+        updateMany: <T = any>(object: string, records: Array<{
+            id: string;
+            data: Partial<T>;
+        }>, options?: BatchOptions) => Promise<BatchUpdateResponse>;
+        delete: (object: string, id: string) => Promise<DeleteDataResult>;
+        deleteMany: (object: string, ids: string[], options?: BatchOptions) => Promise<BatchUpdateResponse>;
+    };
+    /**
+     * 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.
+     */
+    packages: {
+        list: () => Promise<{
+            packages: any[];
+            total: number;
+        }>;
+        get: (id: string, version?: string) => Promise<{
+            package: any;
+        }>;
+    };
+    /**
+     * 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.
+     */
+    automation: {
+        /** Fetch a flow definition by name. */
+        getFlow: <T = any>(name: string) => Promise<T>;
+        /**
+         * Execute (trigger) a flow by name. The request body is forwarded as the
+         * automation execution context (e.g. `{ params, trigger }`).
+         */
+        execute: <T = any>(name: string, ctx?: Record<string, any>) => Promise<T>;
+        /** List recent runs for a flow. */
+        listRuns: <T = any>(flowName: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<T>;
+        /** Fetch a single run (with step log) for a flow. */
+        getRun: <T = any>(flowName: string, runId: string) => Promise<T>;
+    };
+}
 
-export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, RealtimeAPI, type RealtimeEventHandler, type RealtimeSubscriptionFilter, type StandardError, type UpdateDataResult, createFilter, createQuery };
+export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, RealtimeAPI, type RealtimeEventHandler, type RealtimeSubscriptionFilter, ScopedProjectClient, type StandardError, type UpdateDataResult, createFilter, createQuery };