@xcitedbs/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { XCiteDBClient } from './client';
+export { WebSocketSubscription } from './websocket';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery, } from './types';
+export { XCiteDBError } from './types';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XCiteDBError = exports.WebSocketSubscription = exports.XCiteDBClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "XCiteDBClient", { enumerable: true, get: function () { return client_1.XCiteDBClient; } });
+var websocket_1 = require("./websocket");
+Object.defineProperty(exports, "WebSocketSubscription", { enumerable: true, get: function () { return websocket_1.WebSocketSubscription; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "XCiteDBError", { enumerable: true, get: function () { return types_1.XCiteDBError; } });

package/dist/types.d.ts

@@ -0,0 +1,421 @@
+/** Query filters for XCiteDB document APIs */
+export interface XCiteQuery {
+    match?: string;
+    match_start?: string;
+    match_end?: string;
+    contains?: string | string[];
+    regex?: string;
+    /** Restrict to documents that have all of these JSON meta paths (AND). */
+    required_meta_paths?: string[];
+    /** Restrict to documents that have (or had) indexed meta (meta_path_docs sentinel). */
+    filter_any_meta?: boolean;
+    /** Max rows to return (server default 500, max 10000). */
+    limit?: number;
+    /** Skip this many rows (for pagination). */
+    offset?: number;
+}
+/** Full-text search (`POST /api/v1/search`) */
+export interface TextSearchQuery {
+    query: string;
+    doc_types?: ('xml' | 'json')[];
+    branch?: string;
+    offset?: number;
+    limit?: number;
+}
+export interface TextSearchHit {
+    identifier: string;
+    /** Canonical db:xcitepath for XML hits; omitted or empty for JSON. */
+    xcitepath?: string;
+    path: string;
+    doc_type: 'xml' | 'json';
+    branch: string;
+    snippet: string;
+    score: number;
+}
+export interface TextSearchResult {
+    hits: TextSearchHit[];
+    total: number;
+    query: string;
+}
+/** Response from `GET /api/v1/documents/identifiers` */
+export interface ListIdentifiersResult {
+    identifiers: string[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+/** One row from `GET /api/v1/documents/identifier-children` */
+export interface IdentifierChildNode {
+    segment: string;
+    full_path: string;
+    is_identifier: boolean;
+    has_children: boolean;
+}
+/** Response from `GET /api/v1/documents/identifier-children` */
+export interface ListIdentifierChildrenResult {
+    parent_path: string;
+    /** True when `parent_path` is non-empty and names an existing identifier (for “(this path)” in the tree). */
+    parent_is_identifier: boolean;
+    hierarchy_index_available: boolean;
+    children: IdentifierChildNode[];
+}
+export interface LogEntry {
+    identifier: string;
+    branch: string;
+    date: string;
+    action: string;
+}
+export interface LockInfo {
+    lock_id: string;
+    identifier: string;
+    time: number;
+    expiration: number;
+    branch: string;
+}
+export interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+/** Projects from `GET /api/v1/platform/auth/workspaces` (mapped for compatibility). */
+export interface OwnedTenantInfo {
+    tenant_id: string;
+    org_id?: string;
+    name: string;
+    status: string;
+    created_at: string;
+    updated_at?: string;
+    config?: unknown;
+    owner_user_id?: string;
+}
+export interface UserInfo {
+    user_id: string;
+    username: string;
+    tenant_id: string;
+    role: string;
+    email?: string;
+    org_id?: string;
+    org_role?: string;
+    auth_user_type?: string;
+    /** Present for `/api/v1/platform/auth/me` (console / platform JWT). */
+    display_name?: string;
+    groups?: string[];
+    status?: string;
+    current_project_id?: string;
+}
+/** `GET /api/v1/platform/auth/registration-config` */
+export interface PlatformRegistrationConfig {
+    registration_policy: string;
+    organization_mode: string;
+    require_email_verification: boolean;
+}
+/** `GET /api/v1/platform/auth/workspaces` */
+export interface PlatformWorkspaceOrg {
+    org_id: string;
+    name: string;
+    slug: string;
+}
+export interface PlatformWorkspacesResponse {
+    orgs: PlatformWorkspaceOrg[];
+    projects: OwnedTenantInfo[];
+}
+/** One row from `GET /api/v1/project/keys` (secret is never returned). */
+export interface ApiKeyInfo {
+    key_id: string;
+    name: string;
+    prefix: string;
+    expires_at: number;
+    /** `secret` = server-side full access; `public` = client-safe, restricted. */
+    key_type?: 'secret' | 'public';
+}
+export type Flags = 'None' | 'FirstMatch' | 'IncludeChildren' | 'NoChildren' | 'KeepIndexNodes' | 'PrevIfDeleted' | string;
+export interface DatabaseContext {
+    branch?: string;
+    date?: string;
+    prefix?: string;
+    /** Project/tenant id; sent as `tenant_id` in app-user public auth bodies when no developer token is used. */
+    tenant_id?: string;
+}
+export interface WriteDocumentOptions {
+    is_top?: boolean;
+    compare_attributes?: boolean;
+}
+export interface SubscriptionOptions {
+    pattern: string;
+    event_type?: string;
+}
+export interface RealtimeEvent {
+    event: string;
+    identifier?: string;
+    branch?: string;
+    date?: string;
+    timestamp?: number;
+    tenant_id?: string;
+}
+export interface XCiteDBClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    accessToken?: string;
+    /** Optional end-user JWT; combined with developer `accessToken`/`apiKey` as `X-App-User-Token`, or alone as `Authorization` Bearer. */
+    appUserAccessToken?: string;
+    appUserRefreshToken?: string;
+    context?: DatabaseContext;
+    /** When true, sends `X-Project-Id` for console requests; developer JWTs are always platform tokens. */
+    platformConsole?: boolean;
+    /** Active project id for platform console requests (`X-Project-Id` header). */
+    projectId?: string;
+    /** Persist developer session tokens after refresh (e.g. localStorage). */
+    onSessionTokensUpdated?: (pair: TokenPair) => void;
+    /** Persist app-user tokens after refresh. */
+    onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
+    /**
+     * Called when a request returns 401 and refresh (if any) could not recover the session.
+     * Use to clear stored credentials and redirect to sign-in. Not invoked for login/register-style paths.
+     */
+    onSessionInvalid?: () => void;
+}
+/** Application user (tenant-scoped), distinct from developer users. */
+export interface AppUser {
+    user_id: string;
+    email: string;
+    display_name: string;
+    groups: string[];
+    attributes: Record<string, unknown>;
+    status: 'active' | 'disabled' | 'pending_verification';
+    created_at: number;
+    updated_at: number;
+}
+export interface AppUserTokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    user?: AppUser;
+}
+/** `GET /api/v1/app/auth/oauth/providers` */
+export interface OAuthProviderInfo {
+    id: string;
+    display_name: string;
+}
+export interface OAuthProvidersResponse {
+    providers: OAuthProviderInfo[];
+}
+/** Read-only effective `auth.app_users` (GET /api/v1/app/auth/config). */
+export interface AppAuthConfig {
+    enabled: boolean;
+    registration_enabled: boolean;
+    default_groups: string[];
+    require_email_verification: boolean;
+    min_password_length: number;
+    max_login_attempts: number;
+    lockout_duration_seconds: number;
+    access_token_expiry_seconds: number;
+    refresh_token_expiry_seconds: number;
+    reset_token_expiry_seconds: number;
+    verification_token_expiry_seconds: number;
+    jwt_algorithm: string;
+    public_base_url: string;
+}
+export interface AppEmailSmtpConfig {
+    host: string;
+    port: number;
+    username: string;
+    /** Masked as `***` on GET when set; send `***` or empty on PUT to keep previous. */
+    password: string;
+    encryption: string;
+}
+export interface AppEmailWebhookConfig {
+    url: string;
+    secret: string;
+    headers: Record<string, string>;
+}
+/** Effective per-tenant email delivery (merged with server config). */
+export interface AppEmailConfig {
+    delivery_mode: 'none' | 'smtp' | 'webhook' | string;
+    from_email: string;
+    from_name: string;
+    app_name: string;
+    base_url: string;
+    reset_path: string;
+    verify_path: string;
+    smtp: AppEmailSmtpConfig;
+    webhook: AppEmailWebhookConfig;
+}
+export interface AppEmailTemplateEntry {
+    subject: string;
+    html: string;
+    text: string;
+}
+export interface AppEmailTemplates {
+    password_reset?: AppEmailTemplateEntry;
+    email_verification?: AppEmailTemplateEntry;
+}
+export interface ForgotPasswordResponse {
+    delivery: string;
+    reset_token?: string;
+    mail_error?: string;
+}
+export interface SendVerificationResponse {
+    delivery: string;
+    verification_token?: string;
+    mail_error?: string;
+}
+export interface EmailTestResponse {
+    delivery: string;
+    ok: boolean;
+    message?: string;
+    error?: string;
+}
+export interface PolicySubjects {
+    type?: 'app_user' | 'developer' | 'member' | 'any';
+    user_ids?: string[];
+    groups?: string[];
+    not_groups?: string[];
+}
+export interface PolicyIdentifierPattern {
+    exact?: string;
+    match_start?: string;
+    match_end?: string;
+    contains?: string;
+    regex?: string;
+}
+export interface PolicyResources {
+    identifiers?: PolicyIdentifierPattern[];
+    meta_paths?: string[];
+    xml_paths?: string[];
+}
+export interface PolicyConditions {
+    branches?: string[];
+}
+export interface SecurityPolicy {
+    description?: string;
+    effect: 'allow' | 'deny';
+    priority: number;
+    subjects: PolicySubjects;
+    resources: PolicyResources;
+    actions: string[];
+    conditions?: PolicyConditions;
+}
+/** Subject payload for `checkAccess` dry-run. */
+export interface PolicySubjectInput {
+    type?: 'app_user' | 'developer' | 'member' | 'any';
+    user_id?: string;
+    email?: string;
+    groups?: string[];
+    role?: string;
+    username?: string;
+}
+export interface SecurityConfig {
+    default_effect: 'allow' | 'deny';
+    app_user_default_effect: 'allow' | 'deny';
+    developer_bypass: boolean;
+    /** Preferred name; server may only return `developer_bypass`. */
+    member_bypass?: boolean;
+    /** Present on GET /api/v1/security/config; server-derived, not stored on PUT. */
+    xml_paths_enforced?: boolean;
+    xml_paths_pattern_style?: string;
+    xml_paths_limitations?: string[];
+}
+export interface AccessCheckResult {
+    effect: 'allow' | 'deny';
+    matched_policy_id?: string;
+}
+export interface StoredPolicyResponse {
+    policy_id: string;
+    policy: SecurityPolicy;
+    warnings?: string[];
+}
+/** Response from PUT /api/v1/security/policies/{id} */
+export interface PolicyUpdateResponse {
+    message: string;
+    policy_id: string;
+    policy: SecurityPolicy;
+    warnings?: string[];
+}
+/** Stored trigger document under /_xcitedb/triggers (server-defined shape). */
+export type TriggerDefinition = Record<string, unknown>;
+export interface StoredTriggerResponse {
+    trigger_id: string;
+    trigger: TriggerDefinition;
+}
+/** Version control / commit metadata (git-like layer). */
+export interface CommitRecord {
+    id: string;
+    branch: string;
+    /** Internal LMDB date key for this commit snapshot. */
+    date_key: string;
+    date_human?: string;
+    /** Alias for human-readable date (same as date_human when present). */
+    date?: string;
+    message: string;
+    author: string;
+    parent_id: string | null;
+    merge_source?: {
+        branch: string;
+        commit_id: string;
+    };
+    cherry_picked_from?: string;
+    affected_identifiers: string[];
+    status: 'active' | 'rolled_back';
+    created_at: number;
+}
+/** Branch row from GET /api/v1/branches (also exposed as BranchListItem). */
+export interface BranchInfo {
+    name: string;
+    from_branch: string;
+    from_date: string;
+    /** Internal LMDB fork date key when present. */
+    from_date_key?: string;
+    tip_commit?: CommitRecord;
+}
+export type BranchListItem = BranchInfo;
+export interface TagRecord {
+    name: string;
+    commit_id: string;
+    branch: string;
+    date_key: string;
+    message?: string;
+    author?: string;
+    created_at: number;
+}
+export interface DiffEntry {
+    identifier: string;
+    action: 'added' | 'modified' | 'deleted';
+    from_content?: string;
+    to_content?: string;
+}
+export interface DiffRef {
+    branch?: string;
+    /** Internal date key (preferred for exact revision). */
+    date_key?: string;
+    commit_id?: string;
+}
+export interface DiffResult {
+    changes: DiffEntry[];
+    from: {
+        branch?: string;
+        date_key?: string;
+    };
+    to: {
+        branch?: string;
+        date_key?: string;
+    };
+    total_changes: number;
+}
+export interface MergeConflict {
+    identifier: string;
+    source_action: string;
+    target_action: string;
+}
+export interface MergeResult {
+    status: 'completed' | 'conflicts';
+    commit?: CommitRecord;
+    merged_identifiers?: string[];
+    conflicts?: MergeConflict[];
+    auto_mergeable?: string[];
+    message?: string;
+}
+export declare class XCiteDBError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XCiteDBError = void 0;
+class XCiteDBError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'XCiteDBError';
+    }
+}
+exports.XCiteDBError = XCiteDBError;

package/dist/websocket.d.ts

@@ -0,0 +1,27 @@
+import type { RealtimeEvent, SubscriptionOptions } from './types';
+export type MessageHandler = (event: RealtimeEvent) => void;
+export type ErrorHandler = (error: Error) => void;
+/**
+ * Browser / Node 21+ WebSocket client for `/api/v1/ws`.
+ * Pass `access_token` or `X-API-Key` via headers map (used as query params for browser WebSocket).
+ */
+export declare class WebSocketSubscription {
+    private ws;
+    private readonly baseWsUrl;
+    private readonly headerParams;
+    private messageHandler?;
+    private errorHandler?;
+    private reconnectMs;
+    private shouldReconnect;
+    private subs;
+    constructor(baseWsUrl: string, headers: Record<string, string>);
+    private buildUrl;
+    connect(): void;
+    private sendSubscribe;
+    subscribePattern(options: SubscriptionOptions): void;
+    unsubscribePattern(pattern: string): void;
+    ping(): void;
+    onMessage(cb: MessageHandler): void;
+    onError(cb: ErrorHandler): void;
+    close(): void;
+}

package/dist/websocket.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketSubscription = void 0;
+/**
+ * Browser / Node 21+ WebSocket client for `/api/v1/ws`.
+ * Pass `access_token` or `X-API-Key` via headers map (used as query params for browser WebSocket).
+ */
+class WebSocketSubscription {
+    constructor(baseWsUrl, headers) {
+        this.ws = null;
+        this.reconnectMs = 1000;
+        this.shouldReconnect = false;
+        this.subs = [];
+        this.baseWsUrl = baseWsUrl.replace(/\/+$/, '');
+        this.headerParams = { ...headers };
+    }
+    buildUrl() {
+        const u = new URL('/api/v1/ws', `${this.baseWsUrl}/`);
+        const token = this.headerParams['Authorization']?.replace(/^Bearer\s+/i, '');
+        if (token)
+            u.searchParams.set('access_token', token);
+        const apiKey = this.headerParams['X-API-Key'];
+        if (apiKey)
+            u.searchParams.set('api_key', apiKey);
+        const tenant = this.headerParams['tenant_id'];
+        if (tenant)
+            u.searchParams.set('tenant_id', tenant);
+        return u.toString();
+    }
+    connect() {
+        this.shouldReconnect = true;
+        const url = this.buildUrl();
+        this.ws = new WebSocket(url);
+        this.ws.onopen = () => {
+            for (const s of this.subs) {
+                this.sendSubscribe(s);
+            }
+        };
+        this.ws.onmessage = (ev) => {
+            try {
+                const data = JSON.parse(String(ev.data));
+                this.messageHandler?.(data);
+            }
+            catch (e) {
+                this.errorHandler?.(e instanceof Error ? e : new Error(String(e)));
+            }
+        };
+        this.ws.onerror = () => {
+            this.errorHandler?.(new Error('WebSocket error'));
+        };
+        this.ws.onclose = () => {
+            if (this.shouldReconnect) {
+                setTimeout(() => this.connect(), this.reconnectMs);
+            }
+        };
+    }
+    sendSubscribe(opt) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({
+            action: 'subscribe',
+            pattern: opt.pattern,
+            event_type: opt.event_type ?? '*',
+        }));
+    }
+    subscribePattern(options) {
+        this.subs.push(options);
+        this.sendSubscribe(options);
+    }
+    unsubscribePattern(pattern) {
+        this.subs = this.subs.filter((s) => s.pattern !== pattern);
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({ action: 'unsubscribe', pattern }));
+    }
+    ping() {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({ action: 'ping' }));
+    }
+    onMessage(cb) {
+        this.messageHandler = cb;
+    }
+    onError(cb) {
+        this.errorHandler = cb;
+    }
+    close() {
+        this.shouldReconnect = false;
+        this.ws?.close();
+        this.ws = null;
+    }
+}
+exports.WebSocketSubscription = WebSocketSubscription;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@xcitedbs/client",
+  "version": "0.1.0",
+  "description": "XCiteDB BaaS client SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node --test dist/**/*.test.js 2>/dev/null || echo 'No tests'"
+  },
+  "keywords": [
+    "xcitedb",
+    "database",
+    "baas",
+    "client",
+    "api",
+    "websocket"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xcite-db/XciteDB-server.git",
+    "directory": "sdks/javascript"
+  },
+  "bugs": {
+    "url": "https://github.com/xcite-db/XciteDB-server/issues"
+  },
+  "homepage": "https://github.com/xcite-db/XciteDB-server/tree/main/sdks/javascript#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT"
+}