@xcitedbs/client 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @xcitedbs/client
+
+TypeScript/JavaScript client for the **XCiteDB BaaS** HTTP API and WebSocket notifications.
+
+## Install
+
+From npm:
+
+```bash
+npm install @xcitedbs/client
+```
+
+From this repo:
+
+```bash
+cd sdks/javascript && npm install && npm run build
+```
+
+Link or `npm pack` / publish as needed.
+
+## Usage
+
+```typescript
+import { XCiteDBClient } from '@xcitedbs/client';
+
+const client = new XCiteDBClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: process.env.XCITEDB_API_KEY,
+  context: { branch: 'main', date: '03/27/2026' },
+});
+
+await client.health();
+const docs = await client.queryByIdentifier('/test1', 'FirstMatch');
+```
+
+### WebSocket
+
+```typescript
+client.subscribe(
+  { pattern: '/us/bills/*', event_type: '*' },
+  (ev) => console.log(ev)
+);
+```
+
+With JWT in browsers, tokens are passed as `access_token` query parameter on the WebSocket URL. API keys can use `api_key` query parameter.
+
+## Build
+
+```bash
+npm run build
+```
+
+Outputs `dist/` (CommonJS + `.d.ts`).

package/dist/client.d.ts

@@ -0,0 +1,211 @@
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PolicySubjectInput, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { WebSocketSubscription } from './websocket';
+export declare class XCiteDBClient {
+    private baseUrl;
+    private apiKey?;
+    private accessToken?;
+    private refreshToken?;
+    private appUserAccessToken?;
+    private appUserRefreshToken?;
+    private defaultContext;
+    private platformConsole;
+    /** When set with {@link platformConsole}, sent as `X-Project-Id` on API requests. */
+    private projectId?;
+    private onSessionTokensUpdated?;
+    private onAppUserTokensUpdated?;
+    private onSessionInvalid?;
+    constructor(options: XCiteDBClientOptions);
+    /** True if this client would send API key or Bearer credentials on a normal request. */
+    private sentAuthCredentials;
+    /** 401 on these paths is an expected auth flow outcome, not a dead session. */
+    private isSessionInvalidExcludedPath;
+    private notifySessionInvalidIfNeeded;
+    /** Use platform console JWT routes (`/api/v1/platform/auth/*`) for this client instance. */
+    setPlatformConsole(enabled: boolean): void;
+    get isPlatformConsole(): boolean;
+    /** Sets active project for platform console mode (`X-Project-Id`). */
+    setProjectId(projectId: string): void;
+    setContext(ctx: DatabaseContext): void;
+    setTokens(access: string, refresh?: string): void;
+    /** End-user (app) tokens. With developer `accessToken`/`apiKey`, sent as `X-App-User-Token`. */
+    setAppUserTokens(access: string, refresh?: string): void;
+    clearAppUserTokens(): void;
+    private contextHeaders;
+    /** Include `tenant_id` for public app-auth routes when using only app-user tokens (no developer key/JWT). */
+    private mergeAppTenant;
+    private authHeaders;
+    private request;
+    /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
+    private tryRefreshSessionAfter401;
+    private refreshAppUserNoRetry;
+    health(): Promise<{
+        status: string;
+        timestamp?: number;
+    }>;
+    version(): Promise<{
+        version: string;
+        server: string;
+        api_version: string;
+    }>;
+    /**
+     * Platform console sign-in. The first argument is the account **email** (e.g. `admin@localhost`).
+     * Legacy `/api/v1/auth/login` has been removed.
+     */
+    login(email: string, password: string): Promise<TokenPair>;
+    /** Platform console sign-in (`email` + `password`). Project context is `X-Project-Id`, not the JWT. */
+    platformLogin(email: string, password: string): Promise<TokenPair>;
+    refresh(): Promise<TokenPair>;
+    logout(): Promise<void>;
+    me(): Promise<UserInfo>;
+    platformRegistrationConfig(): Promise<PlatformRegistrationConfig>;
+    platformRegister(body: {
+        email: string;
+        password: string;
+        display_name?: string;
+        invite_code?: string;
+        org_action?: 'create' | 'join';
+        org_name?: string;
+        org_id?: string;
+        attributes?: Record<string, unknown>;
+    }): Promise<unknown>;
+    platformWorkspaces(): Promise<PlatformWorkspacesResponse>;
+    listMyTenants(): Promise<OwnedTenantInfo[]>;
+    /** Alias for {@link listMyTenants} (organization/project terminology). */
+    listMyProjects(): Promise<OwnedTenantInfo[]>;
+    /**
+     * Switch active tenant/project for API calls. Platform console: updates `X-Project-Id` only (no token exchange).
+     * Legacy `/api/v1/auth/switch-tenant` has been removed; non-platform callers should set context instead.
+     */
+    switchTenant(tenantId: string): Promise<void>;
+    /** Alias for {@link switchTenant}. */
+    switchProject(projectId: string): Promise<void>;
+    listApiKeys(): Promise<ApiKeyInfo[]>;
+    createApiKey(name: string, expiresAt?: number, keyType?: 'secret' | 'public'): Promise<unknown>;
+    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    revokeApiKey(keyId: string): Promise<void>;
+    registerAppUser(email: string, password: string, displayName?: string, groups?: string[], attributes?: Record<string, unknown>): Promise<AppUser>;
+    getOAuthProviders(): Promise<OAuthProvidersResponse>;
+    /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
+    oauthAuthorizePath(provider: string): string;
+    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    exchangeOAuthCode(code: string): Promise<AppUserTokenPair>;
+    loginAppUser(email: string, password: string): Promise<AppUserTokenPair>;
+    refreshAppUser(): Promise<AppUserTokenPair>;
+    logoutAppUser(): Promise<void>;
+    appUserMe(): Promise<AppUser>;
+    updateAppUserProfile(displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
+    exchangeCustomToken(token: string): Promise<AppUserTokenPair>;
+    /** Change app-user password (requires valid app-user access token). */
+    changeAppUserPassword(currentPassword: string, newPassword: string): Promise<void>;
+    /** Request a password-reset token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
+    forgotAppUserPassword(email: string): Promise<ForgotPasswordResponse>;
+    /** Complete password reset with token from `forgotAppUserPassword` (public; set `context.tenant_id` if no developer auth). */
+    resetAppUserPassword(token: string, newPassword: string): Promise<void>;
+    /** Issue email verification token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
+    sendAppUserVerification(userId: string): Promise<SendVerificationResponse>;
+    getAppAuthConfig(): Promise<AppAuthConfig>;
+    getEmailConfig(): Promise<AppEmailConfig>;
+    updateEmailConfig(config: AppEmailConfig): Promise<AppEmailConfig>;
+    getEmailTemplates(): Promise<AppEmailTemplates>;
+    updateEmailTemplates(templates: AppEmailTemplates): Promise<AppEmailTemplates>;
+    sendTestEmail(to: string): Promise<EmailTestResponse>;
+    /** Verify email with token (public; set `context.tenant_id` if no developer auth). */
+    verifyAppUserEmail(token: string): Promise<void>;
+    listAppUsers(): Promise<AppUser[]>;
+    getAppUser(userId: string): Promise<AppUser>;
+    createAppUser(email: string, password: string, displayName?: string, groups?: string[], attributes?: Record<string, unknown>): Promise<AppUser>;
+    deleteAppUser(userId: string): Promise<void>;
+    updateAppUserGroups(userId: string, groups: string[]): Promise<void>;
+    updateAppUserStatus(userId: string, status: 'active' | 'disabled' | 'pending_verification'): Promise<void>;
+    createPolicy(policyId: string, policy: SecurityPolicy): Promise<StoredPolicyResponse>;
+    listPolicies(): Promise<Record<string, SecurityPolicy>>;
+    getPolicy(policyId: string): Promise<StoredPolicyResponse>;
+    updatePolicy(policyId: string, policy: SecurityPolicy): Promise<PolicyUpdateResponse>;
+    deletePolicy(policyId: string): Promise<void>;
+    upsertTrigger(triggerId: string, trigger: TriggerDefinition): Promise<StoredTriggerResponse>;
+    listTriggers(): Promise<Record<string, TriggerDefinition>>;
+    getTrigger(name: string): Promise<StoredTriggerResponse>;
+    deleteTrigger(name: string): Promise<void>;
+    checkAccess(subject: PolicySubjectInput, identifier: string, action: string, metaPath?: string, branch?: string): Promise<AccessCheckResult>;
+    getSecurityConfig(): Promise<SecurityConfig>;
+    updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
+    createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
+    deleteBranch(name: string): Promise<void>;
+    deleteRevision(branch: string, date: string): Promise<void>;
+    listBranches(): Promise<BranchInfo[]>;
+    getBranch(name: string): Promise<BranchInfo>;
+    createCommit(message: string, author?: string): Promise<CommitRecord>;
+    listCommits(options?: {
+        branch?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        commits: CommitRecord[];
+        total: number;
+        branch: string;
+    }>;
+    getCommit(commitId: string): Promise<CommitRecord>;
+    rollbackToCommit(commitId: string, _confirm?: boolean): Promise<{
+        rolled_back_commits: string[];
+        current_tip: string;
+    }>;
+    cherryPick(commitId: string, message?: string, author?: string): Promise<CommitRecord>;
+    createTag(name: string, commitId: string, message?: string, author?: string): Promise<TagRecord>;
+    listTags(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        tags: TagRecord[];
+        total: number;
+    }>;
+    getTag(name: string): Promise<TagRecord>;
+    deleteTag(name: string): Promise<void>;
+    diff(from: DiffRef, to: DiffRef, includeContent?: boolean): Promise<DiffResult>;
+    mergeBranch(targetBranch: string, sourceBranch: string, options?: {
+        message?: string;
+        autoResolve?: 'none' | 'source' | 'target';
+    }): Promise<MergeResult>;
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeDocumentJson`. */
+    writeXML(xml: string, _options?: WriteDocumentOptions): Promise<void>;
+    writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
+    queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
+    deleteDocument(identifier: string): Promise<void>;
+    addIdentifier(identifier: string): Promise<boolean>;
+    addAlias(original: string, alias: string): Promise<boolean>;
+    queryChangeDate(identifier: string): Promise<string>;
+    getXcitepath(identifier: string): Promise<string>;
+    changedIdentifiers(branch: string, fromDate?: string, toDate?: string): Promise<string[]>;
+    listIdentifiers(query: XCiteQuery): Promise<ListIdentifiersResult>;
+    listIdentifierChildren(parentPath?: string): Promise<ListIdentifierChildrenResult>;
+    queryLog(query: XCiteQuery, fromDate: string, toDate: string): Promise<LogEntry[]>;
+    addMeta(identifier: string, value: unknown, path?: string, opts?: {
+        mode?: 'set' | 'append';
+    }): Promise<boolean>;
+    addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
+        mode?: 'set' | 'append';
+    }): Promise<boolean>;
+    appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
+    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
+    queryMeta(identifier: string, path?: string): Promise<unknown>;
+    queryMetaByQuery(query: XCiteQuery, path?: string): Promise<unknown>;
+    clearMeta(query: XCiteQuery): Promise<boolean>;
+    acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
+    releaseLock(identifier: string, lockId: string): Promise<boolean>;
+    findLocks(identifier: string): Promise<LockInfo[]>;
+    unquery(query: XCiteQuery, unquery: unknown): Promise<unknown>;
+    search(q: TextSearchQuery): Promise<TextSearchResult>;
+    reindex(): Promise<{
+        status: string;
+        message: string;
+    }>;
+    writeJsonDocument(identifier: string, data: unknown): Promise<void>;
+    readJsonDocument(identifier: string): Promise<unknown>;
+    deleteJsonDocument(identifier: string): Promise<void>;
+    listJsonDocuments(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
+    /**
+     * WebSocket `/api/v1/ws` — optional initial subscription pattern.
+     * Uses `access_token` or `api_key` query params when headers are not available (browser).
+     */
+    subscribe(options: SubscriptionOptions, callback: (event: RealtimeEvent) => void, onError?: (err: Error) => void): WebSocketSubscription;
+}