@xcitedbs/client 0.3.7 → 0.3.9

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareDirection, AppUserGroup, CreateGroupParams, ListGroupsResponse } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -500,15 +500,63 @@ export declare class XCiteDBClient {
      * When {@link XCiteDBClient.enableUserIsolation} / `userIsolation` is active, `identifier` is prefixed like other document APIs.
      */
     createUserIsolationShare(params: UserIsolationCreateShareParams): Promise<UserIsolationShareResult>;
+    /**
+     * Revoke a document share previously created with {@link XCiteDBClient.createUserIsolationShare}
+     * (`DELETE /api/v1/security/user-isolation/shares`). Requires an **app user** session.
+     */
+    removeUserIsolationShare(params: UserIsolationUnshareParams): Promise<void>;
+    /**
+     * List document share aliases visible to the caller (`GET /api/v1/security/user-isolation/shares`).
+     * `direction: "outgoing"` is not enumerated server-side — the server returns a `note` and an empty
+     * list; track outgoing shares in the app if needed.
+     */
+    listUserIsolationShares(opts: {
+        direction: ShareDirection;
+        scope?: string;
+    }): Promise<UserIsolationShareListResponse>;
     /** Share an asset path via prefix alias (`POST /api/v1/security/user-isolation/asset-shares`). */
     createAssetShare(params: AssetShareRequest): Promise<UserIsolationShareResult>;
     /** Remove an asset share (`DELETE /api/v1/security/user-isolation/asset-shares`). */
     deleteAssetShare(params: AssetUnshareRequest): Promise<void>;
     /** List incoming/public asset share aliases (`GET /api/v1/security/user-isolation/asset-shares`). */
     listAssetShares(opts?: {
-        direction?: 'incoming' | 'outgoing' | 'public';
+        direction?: ShareDirection;
         scope?: string;
     }): Promise<AssetShareListResponse>;
+    /**
+     * Create an app-user group (`POST /api/v1/security/user-isolation/groups`). Requires an **app user**
+     * session for `kind: "team"` (caller becomes the owner) or a tenant admin for `kind: "admin"`. Use
+     * group ids as `ShareTarget` values to share documents/assets with all current and future members.
+     *
+     * Note: do **not** confuse with {@link XCiteDBClient.updateAppUserGroups}, which is a developer/admin
+     * endpoint that overwrites a user's group list — this endpoint creates the group itself.
+     */
+    createGroup(params: CreateGroupParams): Promise<AppUserGroup>;
+    /**
+     * List groups visible to the caller (`GET /api/v1/security/user-isolation/groups`). For app users,
+     * returns admin groups, groups they own, and groups they belong to.
+     */
+    listGroups(): Promise<ListGroupsResponse>;
+    /** Fetch a single group (`GET /api/v1/security/user-isolation/groups/{id}`). 404 if not visible. */
+    getGroup(id: string): Promise<AppUserGroup>;
+    /** Delete a group (`DELETE /api/v1/security/user-isolation/groups/{id}`). Owner or admin only. */
+    deleteGroup(id: string): Promise<void>;
+    /**
+     * Rename a group (`PATCH /api/v1/security/user-isolation/groups/{id}`). Owner or admin only.
+     * Returns the updated group record. The `group_id` is stable across renames, so existing shares
+     * targeted at this group continue to work.
+     */
+    renameGroup(id: string, name: string): Promise<AppUserGroup>;
+    /**
+     * Add an app user to a group (`POST /api/v1/security/user-isolation/groups/{id}/members`).
+     * Owner or admin only. Returns the updated group record.
+     */
+    addGroupMember(id: string, userId: string): Promise<AppUserGroup>;
+    /**
+     * Remove an app user from a group
+     * (`DELETE /api/v1/security/user-isolation/groups/{id}/members/{user_id}`). Owner or admin only.
+     */
+    removeGroupMember(id: string, userId: string): Promise<void>;
     /** Issue a time-limited magic link for one asset identifier (`POST /api/v1/security/asset-magic-links`). */
     createAssetMagicLink(body: CreateAssetMagicLinkRequest): Promise<AssetMagicLinkResult>;
     /** List issued magic links (no secrets) (`GET /api/v1/security/asset-magic-links`). */

package/dist/client.js

@@ -71,6 +71,18 @@ function buildQuery(params) {
     const s = sp.toString();
     return s ? `?${s}` : '';
 }
+/**
+ * Forward share-target fields (legacy `target_user_id`/`target_group_id` and the preferred `target`
+ * object) into a request body. Server `parseShareTarget` accepts either shape.
+ */
+function applyShareTargetToBody(body, src) {
+    if (src.target_user_id !== undefined)
+        body.target_user_id = src.target_user_id;
+    if (src.target_group_id !== undefined)
+        body.target_group_id = src.target_group_id;
+    if (src.target !== undefined)
+        body.target = src.target;
+}
 /** Best-effort filename from `Content-Disposition` (attachment; filename="…"). */
 function parseContentDispositionFilename(cd) {
     if (!cd)
@@ -1656,18 +1668,45 @@ class XCiteDBClient {
      * When {@link XCiteDBClient.enableUserIsolation} / `userIsolation` is active, `identifier` is prefixed like other document APIs.
      */
     async createUserIsolationShare(params) {
-        return this.request('POST', '/api/v1/security/user-isolation/shares', {
+        const body = {
             identifier: this.isoPrefixId(params.identifier),
-            target_user_id: params.target_user_id,
             mode: params.mode,
+        };
+        applyShareTargetToBody(body, params);
+        return this.request('POST', '/api/v1/security/user-isolation/shares', body);
+    }
+    /**
+     * Revoke a document share previously created with {@link XCiteDBClient.createUserIsolationShare}
+     * (`DELETE /api/v1/security/user-isolation/shares`). Requires an **app user** session.
+     */
+    async removeUserIsolationShare(params) {
+        const body = {
+            identifier: this.isoPrefixId(params.identifier),
+        };
+        applyShareTargetToBody(body, params);
+        if (params.sharer_user_id !== undefined) {
+            body.sharer_user_id = params.sharer_user_id;
+        }
+        await this.request('DELETE', '/api/v1/security/user-isolation/shares', body);
+    }
+    /**
+     * List document share aliases visible to the caller (`GET /api/v1/security/user-isolation/shares`).
+     * `direction: "outgoing"` is not enumerated server-side — the server returns a `note` and an empty
+     * list; track outgoing shares in the app if needed.
+     */
+    async listUserIsolationShares(opts) {
+        const q = buildQuery({
+            direction: opts.direction,
+            ...(opts.scope ? { scope: opts.scope } : {}),
         });
+        return this.request('GET', `/api/v1/security/user-isolation/shares${q}`);
     }
     /** Share an asset path via prefix alias (`POST /api/v1/security/user-isolation/asset-shares`). */
     async createAssetShare(params) {
         const body = {
-            target_user_id: params.target_user_id,
             mode: params.mode,
         };
+        applyShareTargetToBody(body, params);
         if (params.source_uri !== undefined && params.source_uri !== '') {
             body.source_uri = params.source_uri;
         }
@@ -1691,9 +1730,7 @@ class XCiteDBClient {
         else {
             throw new types_1.XCiteDBError('deleteAssetShare requires identifier or source_uri', 400, null);
         }
-        if (params.target_user_id !== undefined) {
-            body.target_user_id = params.target_user_id;
-        }
+        applyShareTargetToBody(body, params);
         if (params.sharer_user_id !== undefined) {
             body.sharer_user_id = params.sharer_user_id;
         }
@@ -1707,6 +1744,57 @@ class XCiteDBClient {
         });
         return this.request('GET', `/api/v1/security/user-isolation/asset-shares${q}`);
     }
+    /**
+     * Create an app-user group (`POST /api/v1/security/user-isolation/groups`). Requires an **app user**
+     * session for `kind: "team"` (caller becomes the owner) or a tenant admin for `kind: "admin"`. Use
+     * group ids as `ShareTarget` values to share documents/assets with all current and future members.
+     *
+     * Note: do **not** confuse with {@link XCiteDBClient.updateAppUserGroups}, which is a developer/admin
+     * endpoint that overwrites a user's group list — this endpoint creates the group itself.
+     */
+    async createGroup(params) {
+        const body = { name: params.name };
+        if (params.kind !== undefined)
+            body.kind = params.kind;
+        return this.request('POST', '/api/v1/security/user-isolation/groups', body);
+    }
+    /**
+     * List groups visible to the caller (`GET /api/v1/security/user-isolation/groups`). For app users,
+     * returns admin groups, groups they own, and groups they belong to.
+     */
+    async listGroups() {
+        return this.request('GET', '/api/v1/security/user-isolation/groups');
+    }
+    /** Fetch a single group (`GET /api/v1/security/user-isolation/groups/{id}`). 404 if not visible. */
+    async getGroup(id) {
+        return this.request('GET', `/api/v1/security/user-isolation/groups/${encodeURIComponent(id)}`);
+    }
+    /** Delete a group (`DELETE /api/v1/security/user-isolation/groups/{id}`). Owner or admin only. */
+    async deleteGroup(id) {
+        await this.request('DELETE', `/api/v1/security/user-isolation/groups/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Rename a group (`PATCH /api/v1/security/user-isolation/groups/{id}`). Owner or admin only.
+     * Returns the updated group record. The `group_id` is stable across renames, so existing shares
+     * targeted at this group continue to work.
+     */
+    async renameGroup(id, name) {
+        return this.request('PATCH', `/api/v1/security/user-isolation/groups/${encodeURIComponent(id)}`, { name });
+    }
+    /**
+     * Add an app user to a group (`POST /api/v1/security/user-isolation/groups/{id}/members`).
+     * Owner or admin only. Returns the updated group record.
+     */
+    async addGroupMember(id, userId) {
+        return this.request('POST', `/api/v1/security/user-isolation/groups/${encodeURIComponent(id)}/members`, { user_id: userId });
+    }
+    /**
+     * Remove an app user from a group
+     * (`DELETE /api/v1/security/user-isolation/groups/{id}/members/{user_id}`). Owner or admin only.
+     */
+    async removeGroupMember(id, userId) {
+        await this.request('DELETE', `/api/v1/security/user-isolation/groups/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`);
+    }
     /** Issue a time-limited magic link for one asset identifier (`POST /api/v1/security/asset-magic-links`). */
     async createAssetMagicLink(body) {
         return this.request('POST', '/api/v1/security/asset-magic-links', body);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, UserIsolationShareListEntry, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareTarget, ShareDirection, AppUserGroup, AppUserGroupKind, CreateGroupParams, ListGroupsResponse, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -278,14 +278,24 @@ export interface AssetShareRequest {
     identifier?: string;
     /** `xcitedb:asset:/…` or raw `/…` path; not prefixed by the client. */
     source_uri?: string;
-    target_user_id: string;
+    /** Legacy: prefer `target`. App user id, `"*"` (public), or `"#anonymous"`. */
+    target_user_id?: string;
+    /** Legacy: prefer `target`. */
+    target_group_id?: string;
+    /** Preferred share-target shape. */
+    target?: ShareTarget;
     mode: UserIsolationShareMode;
 }
 /** Body for `DELETE /api/v1/security/user-isolation/asset-shares`. */
 export interface AssetUnshareRequest {
     identifier?: string;
     source_uri?: string;
+    /** Legacy: prefer `target`. */
     target_user_id?: string;
+    /** Legacy: prefer `target`. */
+    target_group_id?: string;
+    /** Preferred share-target shape. */
+    target?: ShareTarget;
     sharer_user_id?: string;
 }
 export interface AssetShareListEntry {
@@ -652,11 +662,32 @@ export interface UserIsolationConfig {
 }
 /** `read` or `readwrite` for {@link XCiteDBClient.createUserIsolationShare}. */
 export type UserIsolationShareMode = 'read' | 'readwrite';
+/**
+ * Share target for {@link XCiteDBClient.createUserIsolationShare}, {@link XCiteDBClient.createAssetShare},
+ * and the corresponding revoke methods. Server reference: `parseShareTarget` in `SecurityController.cpp`.
+ */
+export type ShareTarget = {
+    type: 'user';
+    id: string;
+} | {
+    type: 'group';
+    id: string;
+} | {
+    type: 'public';
+} | {
+    type: 'anonymous';
+};
+/** Direction filter for {@link XCiteDBClient.listUserIsolationShares} and {@link XCiteDBClient.listAssetShares}. */
+export type ShareDirection = 'incoming' | 'outgoing' | 'public';
 /** Body for `POST /api/v1/security/user-isolation/shares` (app user). */
 export interface UserIsolationCreateShareParams {
     identifier: string;
-    /** Another app user id on the same tenant, or `"*"` for all app users (public alias tree). */
-    target_user_id: string;
+    /** Legacy: prefer `target`. App user id, `"*"` (public), or `"#anonymous"`. */
+    target_user_id?: string;
+    /** Legacy: prefer `target`. App user group id. */
+    target_group_id?: string;
+    /** Preferred share-target shape; supersedes the legacy fields. */
+    target?: ShareTarget;
     mode: UserIsolationShareMode;
 }
 /** JSON body returned with HTTP 201 from create share. */
@@ -664,6 +695,64 @@ export interface UserIsolationShareResult {
     alias: string;
     mode: string;
 }
+/** Single entry in {@link UserIsolationShareListResponse.identifiers}. */
+export interface UserIsolationShareListEntry {
+    identifier: string;
+    mode: UserIsolationShareMode;
+    /** App user id of the user who created this share, parsed from the alias path. */
+    granter_user_id?: string;
+    /** Display name of the granter, looked up at list time. */
+    granter_display_name?: string;
+    /** Email of the granter, looked up at list time. */
+    granter_email?: string;
+    /** Epoch seconds. Omitted for shares created before share-meta storage existed. */
+    created_at?: number;
+}
+/** Response from `GET /api/v1/security/user-isolation/shares?direction=…`. */
+export interface UserIsolationShareListResponse {
+    direction: ShareDirection;
+    identifiers: UserIsolationShareListEntry[];
+    scope?: string;
+    /** Set for `direction: "outgoing"` — server does not enumerate outgoing shares. */
+    note?: string;
+}
+/** Body for `DELETE /api/v1/security/user-isolation/shares` (app user). */
+export interface UserIsolationUnshareParams {
+    identifier: string;
+    /** Legacy: prefer `target`. */
+    target_user_id?: string;
+    /** Legacy: prefer `target`. */
+    target_group_id?: string;
+    /** Preferred share-target shape. */
+    target?: ShareTarget;
+    /** When the caller is the share recipient revoking incoming access; otherwise omit. */
+    sharer_user_id?: string;
+}
+/** App-user group kind. `team` is owned by the creating app user; `admin` is tenant-wide. */
+export type AppUserGroupKind = 'team' | 'admin';
+/** App-user group record returned by group endpoints (`AppUserGroupService::recordToPublicJson`). */
+export interface AppUserGroup {
+    group_id: string;
+    name: string;
+    kind: AppUserGroupKind;
+    /** App user id of the owner. Empty for `kind: "admin"`. */
+    owner_id: string;
+    member_ids: string[];
+    /** Epoch seconds. */
+    created_at: number;
+    /** Epoch seconds. */
+    updated_at: number;
+}
+/** Body for `POST /api/v1/security/user-isolation/groups`. */
+export interface CreateGroupParams {
+    name: string;
+    /** Defaults to `"team"`. `"admin"` requires a tenant-admin caller. */
+    kind?: AppUserGroupKind;
+}
+/** Response from `GET /api/v1/security/user-isolation/groups`. */
+export interface ListGroupsResponse {
+    groups: AppUserGroup[];
+}
 export interface XCiteDBClientOptions {
     baseUrl: string;
     apiKey?: string;

package/dist/user-isolation.test.js

@@ -261,3 +261,165 @@ function slugifyForAssert(name) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 64);
 }
+wd('app-user groups + group-aware shares (wet)', () => {
+    (0, node_test_1.it)('groups lifecycle: owner creates, adds member, non-owner mutation rejected, owner deletes', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const ownerEmail = `js_grp_o_${suffix}@apitest.invalid`;
+        const memberEmail = `js_grp_m_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        let owner;
+        let member;
+        let groupId;
+        try {
+            await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            owner = await admin.createAppUser(ownerEmail, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            member = await admin.createAppUser(memberEmail, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const ownerClient = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await ownerClient.loginAppUser(ownerEmail, password);
+            const created = await ownerClient.createGroup({ name: `g-${suffix}`, kind: 'team' });
+            groupId = created.group_id;
+            strict_1.default.equal(created.kind, 'team');
+            strict_1.default.equal(created.owner_id, owner.user_id);
+            const afterAdd = await ownerClient.addGroupMember(groupId, member.user_id);
+            strict_1.default.ok(afterAdd.member_ids.includes(member.user_id), `member_ids should include ${member.user_id}, got ${JSON.stringify(afterAdd.member_ids)}`);
+            const fetched = await ownerClient.getGroup(groupId);
+            strict_1.default.equal(fetched.name, `g-${suffix}`);
+            strict_1.default.deepEqual(fetched.member_ids.sort(), afterAdd.member_ids.sort());
+            const list = await ownerClient.listGroups();
+            strict_1.default.ok(list.groups.some((g) => g.group_id === groupId), 'listGroups missing created group');
+            // Non-owner cannot mutate.
+            const memberClient = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await memberClient.loginAppUser(memberEmail, password);
+            await strict_1.default.rejects(() => memberClient.deleteGroup(groupId), (err) => {
+                const status = err.status;
+                return status === 403;
+            }, 'non-owner deleteGroup must be rejected with 403');
+            // Rename: owner can; non-owner cannot.
+            const newName = `g-${suffix}-renamed`;
+            const renamed = await ownerClient.renameGroup(groupId, newName);
+            strict_1.default.equal(renamed.name, newName);
+            strict_1.default.equal(renamed.group_id, groupId, 'group_id must be stable across rename');
+            strict_1.default.ok(renamed.updated_at >= created.updated_at, 'updated_at should advance on rename');
+            await strict_1.default.rejects(() => memberClient.renameGroup(groupId, `g-${suffix}-hijack`), (err) => err.status === 403, 'non-owner renameGroup must be rejected with 403');
+            await ownerClient.removeGroupMember(groupId, member.user_id);
+            const afterRemove = await ownerClient.getGroup(groupId);
+            strict_1.default.ok(!afterRemove.member_ids.includes(member.user_id), 'member_ids should not include removed user');
+            await ownerClient.deleteGroup(groupId);
+            groupId = undefined;
+            await strict_1.default.rejects(() => ownerClient.getGroup(created.group_id), (err) => err.status === 404);
+        }
+        finally {
+            if (groupId && owner) {
+                const cleanupClient = new client_js_1.XCiteDBClient({
+                    baseUrl: e.baseUrl,
+                    context: { branch: 'main', project_id: e.tenantId },
+                    userIsolation: { enabled: true },
+                });
+                await cleanupClient.loginAppUser(ownerEmail, password).catch(() => { });
+                await cleanupClient.deleteGroup(groupId).catch(() => { });
+            }
+            if (member)
+                await admin.deleteAppUser(member.user_id).catch(() => { });
+            if (owner)
+                await admin.deleteAppUser(owner.user_id).catch(() => { });
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('group-aware share: owner shares to group, member reads via alias, revoke removes access', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const ownerEmail = `js_gs_o_${suffix}@apitest.invalid`;
+        const memberEmail = `js_gs_m_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const slug = `js-gs-doc-${suffix}`;
+        let owner;
+        let member;
+        let groupId;
+        try {
+            await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            owner = await admin.createAppUser(ownerEmail, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            member = await admin.createAppUser(memberEmail, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const ownerClient = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await ownerClient.loginAppUser(ownerEmail, password);
+            const grp = await ownerClient.createGroup({ name: `gs-${suffix}`, kind: 'team' });
+            groupId = grp.group_id;
+            await ownerClient.addGroupMember(groupId, member.user_id);
+            await ownerClient.writeJsonDocument(`/${slug}`, { _xcite_json_doc: true, who: 'owner', v: 1 });
+            const share = await ownerClient.createUserIsolationShare({
+                identifier: `/${slug}`,
+                target: { type: 'group', id: groupId },
+                mode: 'read',
+            });
+            strict_1.default.ok(share.alias && typeof share.alias === 'string', 'share.alias missing');
+            const memberClient = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await memberClient.loginAppUser(memberEmail, password);
+            const incoming = await memberClient.listUserIsolationShares({ direction: 'incoming' });
+            const matched = incoming.identifiers.find((row) => row.identifier === share.alias);
+            strict_1.default.ok(matched, `incoming list should include alias ${share.alias}; got ${JSON.stringify(incoming.identifiers)}`);
+            strict_1.default.equal(matched.granter_user_id, owner.user_id, 'granter_user_id should match the sharer');
+            strict_1.default.equal(matched.granter_email, ownerEmail, 'granter_email should be the sharer email');
+            strict_1.default.ok(typeof matched.created_at === 'number' && matched.created_at > 0, `created_at should be a positive number; got ${matched.created_at}`);
+            const doc = await memberClient.readJsonDocument(share.alias);
+            strict_1.default.equal(doc.who, 'owner');
+            strict_1.default.equal(doc.v, 1);
+            await ownerClient.removeUserIsolationShare({
+                identifier: `/${slug}`,
+                target: { type: 'group', id: groupId },
+            });
+            await strict_1.default.rejects(() => memberClient.readJsonDocument(share.alias), (err) => {
+                const status = err.status;
+                return status === 403 || status === 404;
+            }, 'after revoke, member read should be 403/404');
+        }
+        finally {
+            if (owner) {
+                await admin.deleteJsonDocument(`/users/${owner.user_id}/${slug}`).catch(() => { });
+            }
+            if (groupId && owner) {
+                const cleanupClient = new client_js_1.XCiteDBClient({
+                    baseUrl: e.baseUrl,
+                    context: { branch: 'main', project_id: e.tenantId },
+                    userIsolation: { enabled: true },
+                });
+                await cleanupClient.loginAppUser(ownerEmail, password).catch(() => { });
+                await cleanupClient.deleteGroup(groupId).catch(() => { });
+            }
+            if (member)
+                await admin.deleteAppUser(member.user_id).catch(() => { });
+            if (owner)
+                await admin.deleteAppUser(owner.user_id).catch(() => { });
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",