pgbeam 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,56 @@
+# pgbeam
+
+TypeScript SDK for the [PgBeam](https://pgbeam.com) API — globally distributed
+PostgreSQL proxy platform with connection pooling and query caching.
+
+## Install
+
+```bash
+npm install pgbeam
+```
+
+## Usage
+
+```ts
+import { PgBeamClient } from "pgbeam";
+
+const client = new PgBeamClient({
+  token: "your-api-token",
+  baseUrl: "https://api.pgbeam.com",
+});
+
+// Tag-based access
+const projects = await client.api.projects.listProjects({
+  queryParams: { org_id: "org_123" },
+});
+
+// Route-based access
+const project = await client.api.request("GET /v1/projects/{project_id}", {
+  pathParams: { project_id: "proj_123" },
+});
+```
+
+## Error handling
+
+```ts
+import { PgBeamClient, ApiError } from "pgbeam";
+
+try {
+  await client.api.projects.getProject({
+    pathParams: { project_id: "proj_123" },
+  });
+} catch (err) {
+  if (err instanceof ApiError) {
+    console.error(err.status, err.message);
+  }
+}
+```
+
+## Operations map
+
+The `pgbeam/operations` export provides route and tag metadata for building
+tooling on top of the SDK:
+
+```ts
+import { operationsByTag, operationsByPath } from "pgbeam/operations";
+```

package/dist/index.cjs

@@ -0,0 +1,568 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _extends = require('@swc/helpers/_/_extends');
+
+/**
+ * Generated by scripts/generate-maps.ts — do not edit manually.
+ * Run: pnpm --filter pgbeam generate
+ */ const operationsByTag = {
+    account: {
+        exportAccountData: {
+            method: "GET",
+            path: "/v1/account/export"
+        },
+        getOnboardingProgress: {
+            method: "GET",
+            path: "/v1/organizations/{org_id}/onboarding"
+        },
+        updateOnboardingProgress: {
+            method: "PATCH",
+            path: "/v1/organizations/{org_id}/onboarding"
+        }
+    },
+    analytics: {
+        getOrganizationActivity: {
+            method: "GET",
+            path: "/v1/organizations/{org_id}/activity"
+        },
+        listPlans: {
+            method: "GET",
+            path: "/v1/plans"
+        },
+        getOrganizationPlan: {
+            method: "GET",
+            path: "/v1/organizations/{org_id}/plan"
+        },
+        updateSpendLimit: {
+            method: "PUT",
+            path: "/v1/organizations/{org_id}/spend-limit"
+        },
+        submitCancellationFeedback: {
+            method: "POST",
+            path: "/v1/organizations/{org_id}/cancellation-feedback"
+        },
+        getProjectInsights: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/insights"
+        },
+        getOrganizationUsage: {
+            method: "GET",
+            path: "/v1/organizations/{org_id}/usage"
+        },
+        getProjectUsage: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/usage"
+        }
+    },
+    projects: {
+        listCacheRules: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/databases/{database_id}/cache-rules"
+        },
+        updateCacheRule: {
+            method: "PUT",
+            path: "/v1/projects/{project_id}/databases/{database_id}/cache-rules/{query_hash}"
+        },
+        listCustomDomains: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/domains"
+        },
+        createCustomDomain: {
+            method: "POST",
+            path: "/v1/projects/{project_id}/domains"
+        },
+        deleteCustomDomain: {
+            method: "DELETE",
+            path: "/v1/projects/{project_id}/domains/{domain_id}"
+        },
+        verifyCustomDomain: {
+            method: "POST",
+            path: "/v1/projects/{project_id}/domains/{domain_id}/verify"
+        },
+        listProjects: {
+            method: "GET",
+            path: "/v1/projects"
+        },
+        createProject: {
+            method: "POST",
+            path: "/v1/projects"
+        },
+        getProject: {
+            method: "GET",
+            path: "/v1/projects/{project_id}"
+        },
+        updateProject: {
+            method: "PATCH",
+            path: "/v1/projects/{project_id}"
+        },
+        deleteProject: {
+            method: "DELETE",
+            path: "/v1/projects/{project_id}"
+        },
+        getProjectMetrics: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/metrics"
+        },
+        listReplicas: {
+            method: "GET",
+            path: "/v1/databases/{database_id}/replicas"
+        },
+        createReplica: {
+            method: "POST",
+            path: "/v1/databases/{database_id}/replicas"
+        },
+        deleteReplica: {
+            method: "DELETE",
+            path: "/v1/databases/{database_id}/replicas/{replica_id}"
+        }
+    },
+    databases: {
+        listDatabases: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/databases"
+        },
+        createDatabase: {
+            method: "POST",
+            path: "/v1/projects/{project_id}/databases"
+        },
+        getDatabase: {
+            method: "GET",
+            path: "/v1/projects/{project_id}/databases/{database_id}"
+        },
+        updateDatabase: {
+            method: "PATCH",
+            path: "/v1/projects/{project_id}/databases/{database_id}"
+        },
+        deleteDatabase: {
+            method: "DELETE",
+            path: "/v1/projects/{project_id}/databases/{database_id}"
+        },
+        testDatabaseConnection: {
+            method: "POST",
+            path: "/v1/projects/{project_id}/databases/{database_id}/test-connection"
+        }
+    },
+    platform: {
+        getHealth: {
+            method: "GET",
+            path: "/v1/health"
+        },
+        listRegions: {
+            method: "GET",
+            path: "/v1/regions"
+        }
+    }
+};
+const operationsByPath = {
+    "GET /v1/account/export": {
+        method: "GET",
+        path: "/v1/account/export",
+        operationId: "exportAccountData"
+    },
+    "GET /v1/organizations/{org_id}/activity": {
+        method: "GET",
+        path: "/v1/organizations/{org_id}/activity",
+        operationId: "getOrganizationActivity"
+    },
+    "GET /v1/plans": {
+        method: "GET",
+        path: "/v1/plans",
+        operationId: "listPlans"
+    },
+    "GET /v1/organizations/{org_id}/plan": {
+        method: "GET",
+        path: "/v1/organizations/{org_id}/plan",
+        operationId: "getOrganizationPlan"
+    },
+    "PUT /v1/organizations/{org_id}/spend-limit": {
+        method: "PUT",
+        path: "/v1/organizations/{org_id}/spend-limit",
+        operationId: "updateSpendLimit"
+    },
+    "POST /v1/organizations/{org_id}/cancellation-feedback": {
+        method: "POST",
+        path: "/v1/organizations/{org_id}/cancellation-feedback",
+        operationId: "submitCancellationFeedback"
+    },
+    "GET /v1/projects/{project_id}/databases/{database_id}/cache-rules": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/databases/{database_id}/cache-rules",
+        operationId: "listCacheRules"
+    },
+    "PUT /v1/projects/{project_id}/databases/{database_id}/cache-rules/{query_hash}": {
+        method: "PUT",
+        path: "/v1/projects/{project_id}/databases/{database_id}/cache-rules/{query_hash}",
+        operationId: "updateCacheRule"
+    },
+    "GET /v1/projects/{project_id}/databases": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/databases",
+        operationId: "listDatabases"
+    },
+    "POST /v1/projects/{project_id}/databases": {
+        method: "POST",
+        path: "/v1/projects/{project_id}/databases",
+        operationId: "createDatabase"
+    },
+    "GET /v1/projects/{project_id}/databases/{database_id}": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/databases/{database_id}",
+        operationId: "getDatabase"
+    },
+    "PATCH /v1/projects/{project_id}/databases/{database_id}": {
+        method: "PATCH",
+        path: "/v1/projects/{project_id}/databases/{database_id}",
+        operationId: "updateDatabase"
+    },
+    "DELETE /v1/projects/{project_id}/databases/{database_id}": {
+        method: "DELETE",
+        path: "/v1/projects/{project_id}/databases/{database_id}",
+        operationId: "deleteDatabase"
+    },
+    "POST /v1/projects/{project_id}/databases/{database_id}/test-connection": {
+        method: "POST",
+        path: "/v1/projects/{project_id}/databases/{database_id}/test-connection",
+        operationId: "testDatabaseConnection"
+    },
+    "GET /v1/projects/{project_id}/domains": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/domains",
+        operationId: "listCustomDomains"
+    },
+    "POST /v1/projects/{project_id}/domains": {
+        method: "POST",
+        path: "/v1/projects/{project_id}/domains",
+        operationId: "createCustomDomain"
+    },
+    "DELETE /v1/projects/{project_id}/domains/{domain_id}": {
+        method: "DELETE",
+        path: "/v1/projects/{project_id}/domains/{domain_id}",
+        operationId: "deleteCustomDomain"
+    },
+    "POST /v1/projects/{project_id}/domains/{domain_id}/verify": {
+        method: "POST",
+        path: "/v1/projects/{project_id}/domains/{domain_id}/verify",
+        operationId: "verifyCustomDomain"
+    },
+    "GET /v1/health": {
+        method: "GET",
+        path: "/v1/health",
+        operationId: "getHealth"
+    },
+    "GET /v1/projects/{project_id}/insights": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/insights",
+        operationId: "getProjectInsights"
+    },
+    "GET /v1/organizations/{org_id}/onboarding": {
+        method: "GET",
+        path: "/v1/organizations/{org_id}/onboarding",
+        operationId: "getOnboardingProgress"
+    },
+    "PATCH /v1/organizations/{org_id}/onboarding": {
+        method: "PATCH",
+        path: "/v1/organizations/{org_id}/onboarding",
+        operationId: "updateOnboardingProgress"
+    },
+    "GET /v1/projects": {
+        method: "GET",
+        path: "/v1/projects",
+        operationId: "listProjects"
+    },
+    "POST /v1/projects": {
+        method: "POST",
+        path: "/v1/projects",
+        operationId: "createProject"
+    },
+    "GET /v1/projects/{project_id}": {
+        method: "GET",
+        path: "/v1/projects/{project_id}",
+        operationId: "getProject"
+    },
+    "PATCH /v1/projects/{project_id}": {
+        method: "PATCH",
+        path: "/v1/projects/{project_id}",
+        operationId: "updateProject"
+    },
+    "DELETE /v1/projects/{project_id}": {
+        method: "DELETE",
+        path: "/v1/projects/{project_id}",
+        operationId: "deleteProject"
+    },
+    "GET /v1/projects/{project_id}/metrics": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/metrics",
+        operationId: "getProjectMetrics"
+    },
+    "GET /v1/regions": {
+        method: "GET",
+        path: "/v1/regions",
+        operationId: "listRegions"
+    },
+    "GET /v1/databases/{database_id}/replicas": {
+        method: "GET",
+        path: "/v1/databases/{database_id}/replicas",
+        operationId: "listReplicas"
+    },
+    "POST /v1/databases/{database_id}/replicas": {
+        method: "POST",
+        path: "/v1/databases/{database_id}/replicas",
+        operationId: "createReplica"
+    },
+    "DELETE /v1/databases/{database_id}/replicas/{replica_id}": {
+        method: "DELETE",
+        path: "/v1/databases/{database_id}/replicas/{replica_id}",
+        operationId: "deleteReplica"
+    },
+    "GET /v1/organizations/{org_id}/usage": {
+        method: "GET",
+        path: "/v1/organizations/{org_id}/usage",
+        operationId: "getOrganizationUsage"
+    },
+    "GET /v1/projects/{project_id}/usage": {
+        method: "GET",
+        path: "/v1/projects/{project_id}/usage",
+        operationId: "getProjectUsage"
+    }
+};
+
+class ApiError extends Error {
+    constructor(status, statusText, body){
+        var _extractMessage;
+        const message = typeof body === "object" && body !== null ? (_extractMessage = extractMessage(body)) != null ? _extractMessage : statusText : statusText;
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}
+/** Extract a human-readable message from an API error body. */ function extractMessage(body) {
+    if (typeof body !== "object" || body === null) return undefined;
+    const obj = body;
+    // API returns { error: { code, message } }
+    if (typeof obj.error === "object" && obj.error !== null) {
+        const inner = obj.error;
+        if (typeof inner.message === "string") return inner.message;
+    }
+    if (typeof obj.message === "string") return obj.message;
+    return undefined;
+}
+const RETRYABLE_STATUS_CODES = new Set([
+    408,
+    429,
+    502,
+    503,
+    504
+]);
+const DEFAULT_RETRY = {
+    maxRetries: 5,
+    initialDelayMs: 500,
+    maxDelayMs: 30000,
+    idempotencyKeys: true
+};
+function resolveRetry(config) {
+    if (!config) return _extends._({}, DEFAULT_RETRY, {
+        maxRetries: 0
+    });
+    return _extends._({}, DEFAULT_RETRY, config);
+}
+/** Parse Retry-After header as milliseconds. Returns undefined if unparseable. */ function parseRetryAfter(response) {
+    const header = response.headers.get("Retry-After");
+    if (!header) return undefined;
+    // Integer seconds
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1000;
+    }
+    // HTTP-date
+    const date = Date.parse(header);
+    if (Number.isFinite(date)) {
+        const ms = date - Date.now();
+        return ms > 0 ? ms : 0;
+    }
+    return undefined;
+}
+/** Compute exponential backoff with jitter. */ function backoff(attempt, initialDelayMs, maxDelayMs) {
+    const delay = Math.min(initialDelayMs * 2 ** attempt, maxDelayMs);
+    return delay * (0.5 + Math.random());
+}
+/** Generate a UUID v4 using crypto.randomUUID if available, otherwise fallback. */ function generateUUID() {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without crypto.randomUUID
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c)=>{
+        const r = Math.random() * 16 | 0;
+        const v = c === "x" ? r : r & 0x3 | 0x8;
+        return v.toString(16);
+    });
+}
+function isMutatingMethod(method) {
+    const upper = method.toUpperCase();
+    return upper === "POST" || upper === "PATCH";
+}
+async function fetcher(options) {
+    var _options_fetchImpl;
+    let url = options.path;
+    if (options.pathParams) {
+        for (const [key, value] of Object.entries(options.pathParams)){
+            url = url.replace(`{${key}}`, encodeURIComponent(value));
+        }
+    }
+    const fullUrl = new URL(url, options.baseUrl);
+    if (options.queryParams) {
+        for (const [key, value] of Object.entries(options.queryParams)){
+            if (value !== undefined && value !== null) {
+                fullUrl.searchParams.set(key, String(value));
+            }
+        }
+    }
+    const headers = {};
+    if (options.token) {
+        headers.Authorization = `Bearer ${options.token}`;
+    }
+    if (options.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+    }
+    const fetchFn = (_options_fetchImpl = options.fetchImpl) != null ? _options_fetchImpl : globalThis.fetch;
+    const retry = resolveRetry(options.retry);
+    const urlStr = fullUrl.toString();
+    const fetchBody = options.body !== undefined ? JSON.stringify(options.body) : undefined;
+    // Generate idempotency key once, reused across all retry attempts.
+    const idempotencyKey = retry.maxRetries > 0 && retry.idempotencyKeys && isMutatingMethod(options.method) ? generateUUID() : undefined;
+    for(let attempt = 0; attempt <= retry.maxRetries; attempt++){
+        const reqHeaders = _extends._({}, headers);
+        // Attach idempotency key on all attempts for mutating requests.
+        if (idempotencyKey) {
+            reqHeaders["Idempotency-Key"] = idempotencyKey;
+        }
+        try {
+            var _parseRetryAfter;
+            const response = await fetchFn(urlStr, {
+                method: options.method,
+                headers: reqHeaders,
+                body: fetchBody
+            });
+            if (options.onResponse) {
+                await options.onResponse(response);
+            }
+            if (response.ok) {
+                return parseResponseBody(response);
+            }
+            // Non-retryable error or last attempt — throw immediately.
+            if (!RETRYABLE_STATUS_CODES.has(response.status) || attempt === retry.maxRetries) {
+                const errorBody = await response.json().catch(()=>null);
+                throw new ApiError(response.status, response.statusText, errorBody);
+            }
+            // Retryable error — wait and retry.
+            const delay = (_parseRetryAfter = parseRetryAfter(response)) != null ? _parseRetryAfter : backoff(attempt, retry.initialDelayMs, retry.maxDelayMs);
+            await sleep(delay);
+        } catch (err) {
+            // If it's already an ApiError, rethrow (we threw it above).
+            if (err instanceof ApiError) throw err;
+            // Network error — retry if we have attempts left.
+            if (attempt === retry.maxRetries) throw err;
+            const delay = backoff(attempt, retry.initialDelayMs, retry.maxDelayMs);
+            await sleep(delay);
+        }
+    }
+    // Unreachable — the loop either returns or throws.
+    throw new Error("fetcher: exhausted all retry attempts");
+}
+async function parseResponseBody(response) {
+    if (response.status === 204) return undefined;
+    const contentType = response.headers.get("content-type");
+    if (contentType == null ? void 0 : contentType.includes("application/json")) {
+        return response.json();
+    }
+    // Fallback: try JSON, return undefined if body is empty/non-JSON
+    const text = await response.text();
+    if (!text) return undefined;
+    try {
+        return JSON.parse(text);
+    } catch (unused) {
+        return undefined;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve)=>setTimeout(resolve, ms));
+}
+
+class PgBeamClient {
+    async _resolveToken() {
+        if (typeof this._tokenOrFn === "function") {
+            return this._tokenOrFn();
+        }
+        return this._tokenOrFn;
+    }
+    _call(method, path) {
+        return async (params = {})=>{
+            const token = await this._resolveToken();
+            return fetcher({
+                method,
+                path,
+                pathParams: params.pathParams,
+                queryParams: params.queryParams,
+                body: params.body,
+                baseUrl: this._baseUrl,
+                token,
+                fetchImpl: this._fetchImpl,
+                onResponse: this._onResponse,
+                retry: this._retry
+            });
+        };
+    }
+    /** Access API operations via tag-based namespaces or `.request()`. */ get api() {
+        if (this._api) return this._api;
+        const request = async (route, params)=>{
+            const meta = operationsByPath[route];
+            if (!meta) throw new Error(`Unknown route: ${String(route)}`);
+            const token = await this._resolveToken();
+            return fetcher({
+                method: meta.method,
+                path: meta.path,
+                pathParams: params == null ? void 0 : params.pathParams,
+                queryParams: params == null ? void 0 : params.queryParams,
+                body: params == null ? void 0 : params.body,
+                baseUrl: this._baseUrl,
+                token,
+                fetchImpl: this._fetchImpl,
+                onResponse: this._onResponse,
+                retry: this._retry
+            });
+        };
+        this._api = new Proxy({}, {
+            get: (_, prop)=>{
+                if (prop === "request") return request;
+                const tagOps = operationsByTag[prop];
+                if (!tagOps) return undefined;
+                return new Proxy({}, {
+                    get: (_, method)=>{
+                        const ops = tagOps;
+                        const opMeta = ops[method];
+                        if (!opMeta) return undefined;
+                        return this._call(opMeta.method, opMeta.path);
+                    }
+                });
+            }
+        });
+        return this._api;
+    }
+    constructor(options){
+        var _options_retry;
+        this._baseUrl = options.baseUrl;
+        this._tokenOrFn = options.token;
+        this._fetchImpl = options.fetch;
+        this._onResponse = options.onResponse;
+        this._retry = options.retry === false ? {
+            maxRetries: 0
+        } : (_options_retry = options.retry) != null ? _options_retry : {
+            maxRetries: 5
+        };
+    }
+}
+
+exports.ApiError = ApiError;
+exports.PgBeamClient = PgBeamClient;
+exports.extractMessage = extractMessage;