pacificdb-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * PacificDB connection string parsing, building, and redaction.
+ *
+ * Format:
+ * pacificdb://<user>:<password>@<clusterHost>/<databaseName>
+ *   ?projectId=..&clusterId=..&databaseId=..&tls=true&authSource=admin&appName=..
+ */
+interface PacificConnectionString {
+    protocol: 'pacificdb';
+    username: string;
+    password: string;
+    clusterHost: string;
+    databaseName: string;
+    orgId: string;
+    projectId: string;
+    clusterId: string;
+    databaseId: string;
+    tls: boolean;
+    authSource: string;
+    appName?: string;
+}
+declare function parseConnectionString(uri: string): PacificConnectionString;
+declare function buildConnectionString(input: Omit<PacificConnectionString, 'protocol'>): string;
+/** Replace the password portion of a URI with REDACTED. Never throws. */
+declare function redactConnectionString(uri: string): string;
+/** Deep-copy a value with secret-looking keys replaced by REDACTED. */
+declare function redactSecrets(value: unknown): unknown;
+
+/**
+ * PacificDBClient - database client over the PacificDB gateway data plane.
+ *
+ * Auth: exchanges the connection string credentials for a short-lived database
+ * session (POST /api/v1/db/sessions), then sends Bearer session tokens.
+ * Sessions are transparently refreshed once when the server reports 401.
+ *
+ * Retries: exponential backoff with jitter for server_busy / not_leader /
+ * 429 / 503 / timeouts, bounded by retryLimit.
+ *
+ * Logging: optional logger receives structured events; connection strings and
+ * passwords are always redacted before they reach the logger.
+ */
+
+interface PacificDBLogger {
+    debug?(message: string, fields?: Record<string, unknown>): void;
+    warn?(message: string, fields?: Record<string, unknown>): void;
+}
+interface PacificDBClientOptions {
+    /** Override the gateway base URL (defaults to https://<clusterHost>). */
+    apiUrl?: string;
+    /** Allow http:// gateways (local development only). */
+    allowInsecure?: boolean;
+    fetch?: typeof fetch;
+    /** Timeout for read operations (find). Default 30s. */
+    readTimeoutMs?: number;
+    /** Timeout for write operations (insert/update/delete). Default 30s. */
+    writeTimeoutMs?: number;
+    retryLimit?: number;
+    retryBackoffMs?: number;
+    logger?: PacificDBLogger;
+    appName?: string;
+}
+interface FindOptions {
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+}
+interface CollectionHandle<T extends Record<string, unknown> = Record<string, unknown>> {
+    insertOne(document: T): Promise<{
+        inserted: boolean;
+        id: string | null;
+    }>;
+    findOne(filter: Partial<T>): Promise<T | null>;
+    find(filter: Partial<T>, options?: FindOptions): Promise<T[]>;
+    updateOne(filter: Partial<T>, update: Record<string, unknown>): Promise<unknown>;
+    deleteOne(filter: Partial<T>): Promise<unknown>;
+}
+interface ModelHandle<T extends Record<string, unknown> = Record<string, unknown>> {
+    create(document: T): Promise<{
+        inserted: boolean;
+        id: string | null;
+    }>;
+    findOne(filter: Partial<T>): Promise<T | null>;
+    find(filter: Partial<T>, options?: FindOptions): Promise<T[]>;
+    updateOne(filter: Partial<T>, update: Record<string, unknown>): Promise<unknown>;
+    deleteOne(filter: Partial<T>): Promise<unknown>;
+}
+type ModelSchema = Record<string, unknown>;
+declare class PacificDBClient {
+    readonly connection: PacificConnectionString;
+    private readonly fetchImpl;
+    private readonly apiUrl;
+    private readonly readTimeoutMs;
+    private readonly writeTimeoutMs;
+    private readonly retryLimit;
+    private readonly retryBackoffMs;
+    private readonly logger?;
+    private sessionToken;
+    private connected;
+    constructor(uri: string, options?: PacificDBClientOptions);
+    /** The redacted URI (safe for logs/errors). */
+    get redactedUri(): string;
+    connect(): Promise<void>;
+    private authenticate;
+    close(): Promise<void>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionHandle<T>;
+    model<T extends Record<string, unknown> = Record<string, unknown>>(name: string, schema: ModelSchema): ModelHandle<T>;
+    private request;
+    private backoff;
+}
+
+/**
+ * Typed error hierarchy for the PacificDB client.
+ */
+declare class PacificDBError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(message: string, code?: string, requestId?: string);
+}
+/** Invalid connection string or client configuration. */
+declare class PacificDBConfigError extends PacificDBError {
+    constructor(message: string);
+}
+/** Authentication or session failure (401-class). */
+declare class PacificDBAuthError extends PacificDBError {
+    constructor(message: string, requestId?: string);
+}
+/** Non-retriable client-side failure (4xx-class). */
+declare class PacificDBClientError extends PacificDBError {
+    readonly status: number;
+    constructor(message: string, code: string, status: number, requestId?: string);
+}
+/** Retriable server-side failure (5xx-class, server_busy, not_leader). */
+declare class PacificDBServerError extends PacificDBError {
+    readonly status: number;
+    constructor(message: string, code: string, status: number, requestId?: string);
+}
+/** Request exceeded the configured timeout. */
+declare class PacificDBTimeoutError extends PacificDBError {
+    constructor(timeoutMs: number, requestId?: string);
+}
+
+export { type CollectionHandle, type FindOptions, type ModelHandle, type PacificConnectionString, PacificDBAuthError, PacificDBClient, PacificDBClientError, type PacificDBClientOptions, PacificDBConfigError, PacificDBError, type PacificDBLogger, PacificDBServerError, PacificDBTimeoutError, buildConnectionString, parseConnectionString, redactConnectionString, redactSecrets };

package/dist/index.js

@@ -0,0 +1,340 @@
+// src/errors.ts
+var PacificDBError = class extends Error {
+  code;
+  requestId;
+  constructor(message, code = "PACIFICDB_ERROR", requestId) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.requestId = requestId;
+  }
+};
+var PacificDBConfigError = class extends PacificDBError {
+  constructor(message) {
+    super(message, "CONFIG_ERROR");
+  }
+};
+var PacificDBAuthError = class extends PacificDBError {
+  constructor(message, requestId) {
+    super(message, "AUTH_ERROR", requestId);
+  }
+};
+var PacificDBClientError = class extends PacificDBError {
+  status;
+  constructor(message, code, status, requestId) {
+    super(message, code, requestId);
+    this.status = status;
+  }
+};
+var PacificDBServerError = class extends PacificDBError {
+  status;
+  constructor(message, code, status, requestId) {
+    super(message, code, requestId);
+    this.status = status;
+  }
+};
+var PacificDBTimeoutError = class extends PacificDBError {
+  constructor(timeoutMs, requestId) {
+    super(`PacificDB request timed out after ${timeoutMs}ms`, "TIMEOUT", requestId);
+  }
+};
+
+// src/connectionString.ts
+var SECRET_KEYS = /* @__PURE__ */ new Set(["password", "token", "secret", "key", "sessiontoken", "connectionstring"]);
+function parseConnectionString(uri) {
+  let url;
+  try {
+    url = new URL(uri);
+  } catch (error) {
+    throw new PacificDBConfigError(`Invalid PacificDB connection string: ${error.message}`);
+  }
+  const protocol = url.protocol.replace(":", "");
+  if (protocol !== "pacificdb") {
+    throw new PacificDBConfigError("PacificDB connection strings must use the pacificdb:// protocol.");
+  }
+  if (!url.username || !url.password) {
+    throw new PacificDBConfigError("PacificDB connection string requires a database username and password.");
+  }
+  const databaseName = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+  if (!databaseName) {
+    throw new PacificDBConfigError("PacificDB connection string requires a database name path.");
+  }
+  const orgId = url.searchParams.get("orgId") || url.searchParams.get("organizationId") || "";
+  const projectId = url.searchParams.get("projectId") || "";
+  const clusterId = url.searchParams.get("clusterId") || "";
+  const databaseId = url.searchParams.get("databaseId") || "";
+  if (!orgId || !projectId || !clusterId || !databaseId) {
+    throw new PacificDBConfigError("PacificDB connection string requires orgId, projectId, clusterId, and databaseId.");
+  }
+  const tlsRaw = url.searchParams.get("tls");
+  return {
+    protocol: "pacificdb",
+    username: decodeURIComponent(url.username),
+    password: decodeURIComponent(url.password),
+    clusterHost: url.host,
+    databaseName,
+    orgId,
+    projectId,
+    clusterId,
+    databaseId,
+    tls: tlsRaw === null ? true : tlsRaw !== "false",
+    authSource: url.searchParams.get("authSource") || "admin",
+    appName: url.searchParams.get("appName") || void 0
+  };
+}
+function buildConnectionString(input) {
+  const url = new URL(`pacificdb://${input.clusterHost}/${encodeURIComponent(input.databaseName)}`);
+  url.username = encodeURIComponent(input.username);
+  url.password = encodeURIComponent(input.password);
+  if (input.orgId) url.searchParams.set("orgId", input.orgId);
+  url.searchParams.set("projectId", input.projectId);
+  url.searchParams.set("clusterId", input.clusterId);
+  url.searchParams.set("databaseId", input.databaseId);
+  url.searchParams.set("tls", String(input.tls !== false));
+  url.searchParams.set("authSource", input.authSource || "admin");
+  if (input.appName) url.searchParams.set("appName", input.appName);
+  return url.toString();
+}
+function redactConnectionString(uri) {
+  try {
+    const url = new URL(uri);
+    if (url.password) url.password = "REDACTED";
+    return url.toString();
+  } catch {
+    return uri.replace(/(pacificdb:\/\/[^:]+:)[^@]+@/i, "$1REDACTED@");
+  }
+}
+function redactSecrets(value) {
+  if (!value || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(redactSecrets);
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    out[key] = SECRET_KEYS.has(key.toLowerCase()) ? "REDACTED" : redactSecrets(item);
+  }
+  return out;
+}
+
+// src/client.ts
+var RETRIABLE_CODES = /* @__PURE__ */ new Set(["server_busy", "not_leader", "TIMEOUT", "RATE_LIMITED", "HTTP_503", "HTTP_429", "ENGINE_UNAVAILABLE"]);
+function randomRequestId() {
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var PacificDBClient = class {
+  connection;
+  fetchImpl;
+  apiUrl;
+  readTimeoutMs;
+  writeTimeoutMs;
+  retryLimit;
+  retryBackoffMs;
+  logger;
+  sessionToken = "";
+  connected = false;
+  constructor(uri, options = {}) {
+    this.connection = parseConnectionString(uri);
+    this.apiUrl = (options.apiUrl || `https://${this.connection.clusterHost}`).replace(/\/+$/, "");
+    if (this.apiUrl.startsWith("http://") && !options.allowInsecure) {
+      throw new PacificDBConfigError(
+        "Refusing to send database credentials over http://. Use https, or pass { allowInsecure: true } for local development."
+      );
+    }
+    const fetchImpl = options.fetch || (typeof fetch !== "undefined" ? fetch : void 0);
+    if (!fetchImpl) {
+      throw new PacificDBConfigError("No fetch implementation available. Use Node.js >= 18 or pass options.fetch.");
+    }
+    this.fetchImpl = fetchImpl;
+    this.readTimeoutMs = options.readTimeoutMs ?? 3e4;
+    this.writeTimeoutMs = options.writeTimeoutMs ?? 3e4;
+    this.retryLimit = options.retryLimit ?? 3;
+    this.retryBackoffMs = options.retryBackoffMs ?? 250;
+    this.logger = options.logger;
+  }
+  /** The redacted URI (safe for logs/errors). */
+  get redactedUri() {
+    return redactConnectionString(
+      `pacificdb://${encodeURIComponent(this.connection.username)}:x@${this.connection.clusterHost}/${this.connection.databaseName}`
+    );
+  }
+  async connect() {
+    await this.authenticate();
+    this.connected = true;
+  }
+  async authenticate() {
+    const result = await this.request("POST", "/api/v1/db/sessions", {
+      username: this.connection.username,
+      password: this.connection.password,
+      orgId: this.connection.orgId,
+      projectId: this.connection.projectId,
+      clusterId: this.connection.clusterId,
+      databaseId: this.connection.databaseId,
+      databaseName: this.connection.databaseName,
+      authSource: this.connection.authSource
+    }, { requireSession: false, isWrite: true });
+    if (!result?.sessionToken) {
+      throw new PacificDBAuthError("Database authentication did not return a session token.");
+    }
+    this.sessionToken = result.sessionToken;
+    this.logger?.debug?.("pacificdb.session.created", { database: this.connection.databaseName });
+  }
+  async close() {
+    if (!this.sessionToken) return;
+    try {
+      await this.request("DELETE", "/api/v1/db/sessions/current", void 0, { isWrite: true });
+    } catch {
+    } finally {
+      this.sessionToken = "";
+      this.connected = false;
+    }
+  }
+  collection(name) {
+    const encoded = encodeURIComponent(name);
+    return {
+      insertOne: async (document) => {
+        const r = await this.request(
+          "POST",
+          `/api/v1/db/collections/${encoded}/documents`,
+          { document },
+          { isWrite: true }
+        );
+        return { inserted: r?.inserted !== false, id: r?.id ?? null };
+      },
+      findOne: async (filter) => {
+        const r = await this.request(
+          "POST",
+          `/api/v1/db/collections/${encoded}/find`,
+          { query: filter, limit: 1 },
+          { isWrite: false }
+        );
+        return r?.documents?.[0] ?? null;
+      },
+      find: async (filter, options = {}) => {
+        const r = await this.request(
+          "POST",
+          `/api/v1/db/collections/${encoded}/find`,
+          { query: filter, ...options },
+          { isWrite: false }
+        );
+        return r?.documents ?? [];
+      },
+      updateOne: (filter, update) => this.request("PATCH", `/api/v1/db/collections/${encoded}/documents`, { filter, update }, { isWrite: true }),
+      deleteOne: (filter) => this.request("DELETE", `/api/v1/db/collections/${encoded}/documents`, { filter }, { isWrite: true })
+    };
+  }
+  model(name, schema) {
+    const collection = this.collection(name);
+    const validate = (document) => {
+      for (const [field, type] of Object.entries(schema)) {
+        const value = document[field];
+        if (value === void 0 || value === null) continue;
+        const expected = typeof type === "function" ? type.name?.toLowerCase() : void 0;
+        if (expected && expected !== "object" && typeof value !== expected) {
+          throw new PacificDBConfigError(`Field "${field}" expected ${expected}, got ${typeof value}.`);
+        }
+      }
+    };
+    return {
+      create: async (document) => {
+        validate(document);
+        return collection.insertOne(document);
+      },
+      findOne: (filter) => collection.findOne(filter),
+      find: (filter, options) => collection.find(filter, options),
+      updateOne: (filter, update) => collection.updateOne(filter, update),
+      deleteOne: (filter) => collection.deleteOne(filter)
+    };
+  }
+  async request(method, path, body, opts = {}) {
+    const { requireSession = true, isWrite = false } = opts;
+    if (requireSession && !this.sessionToken) {
+      throw new PacificDBAuthError("Call connect() before issuing database operations.");
+    }
+    const timeoutMs = isWrite ? this.writeTimeoutMs : this.readTimeoutMs;
+    const url = new URL(path, `${this.apiUrl}/`);
+    url.searchParams.set("projectId", this.connection.projectId);
+    url.searchParams.set("clusterId", this.connection.clusterId);
+    url.searchParams.set("databaseId", this.connection.databaseId);
+    let refreshed = false;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retryLimit; attempt++) {
+      const requestId = randomRequestId();
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await this.fetchImpl(url, {
+          method,
+          signal: controller.signal,
+          headers: {
+            "content-type": "application/json",
+            "x-request-id": requestId,
+            ...this.sessionToken ? { authorization: `Bearer ${this.sessionToken}` } : {}
+          },
+          body: body === void 0 ? void 0 : JSON.stringify(body)
+        });
+        clearTimeout(timer);
+        const json = await response.json().catch(() => ({}));
+        if (response.ok && json.success !== false) {
+          return json.data ?? json;
+        }
+        const errObj = typeof json.error === "object" ? json.error : void 0;
+        const code = errObj?.code || (typeof json.error === "string" ? json.error : "") || `HTTP_${response.status}`;
+        const message = errObj?.message || `PacificDB request failed (${code})`;
+        if (response.status === 401 && this.connected && !refreshed && requireSession) {
+          refreshed = true;
+          this.logger?.debug?.("pacificdb.session.refresh", { requestId });
+          await this.authenticate();
+          attempt--;
+          continue;
+        }
+        if (response.status === 401) {
+          throw new PacificDBAuthError(message, requestId);
+        }
+        const retriable = RETRIABLE_CODES.has(code) || response.status === 429 || response.status === 503;
+        if (!retriable || attempt === this.retryLimit) {
+          if (response.status >= 500) throw new PacificDBServerError(message, code, response.status, requestId);
+          throw new PacificDBClientError(message, code, response.status, requestId);
+        }
+        const retryAfter = Number(response.headers.get("retry-after-ms") || json.retry_after_ms || 0);
+        lastError = new PacificDBServerError(message, code, response.status, requestId);
+        await this.backoff(attempt, retryAfter);
+      } catch (error) {
+        clearTimeout(timer);
+        if (error instanceof PacificDBClientError || error instanceof PacificDBAuthError || error instanceof PacificDBConfigError || error instanceof PacificDBServerError) {
+          if (error instanceof PacificDBServerError && attempt < this.retryLimit) {
+            lastError = error;
+            await this.backoff(attempt, 0);
+            continue;
+          }
+          throw error;
+        }
+        const isAbort = error.name === "AbortError";
+        lastError = isAbort ? new PacificDBTimeoutError(timeoutMs) : error;
+        this.logger?.warn?.("pacificdb.request.retry", {
+          attempt,
+          code: isAbort ? "TIMEOUT" : "NETWORK_ERROR",
+          target: this.redactedUri
+        });
+        if (attempt === this.retryLimit) break;
+        await this.backoff(attempt, 0);
+      }
+    }
+    throw lastError || new PacificDBServerError("PacificDB request failed.", "UNKNOWN", 0);
+  }
+  backoff(attempt, retryAfterMs) {
+    const base = retryAfterMs || this.retryBackoffMs * Math.pow(2, attempt);
+    const jitter = Math.floor(Math.random() * this.retryBackoffMs);
+    return new Promise((resolve) => setTimeout(resolve, base + jitter));
+  }
+};
+export {
+  PacificDBAuthError,
+  PacificDBClient,
+  PacificDBClientError,
+  PacificDBConfigError,
+  PacificDBError,
+  PacificDBServerError,
+  PacificDBTimeoutError,
+  buildConnectionString,
+  parseConnectionString,
+  redactConnectionString,
+  redactSecrets
+};