@polardbx/pxbaas-client 0.0.0-stage → 0.1.0-beta.1

package/dist/drivers/storage.driver.js

@@ -0,0 +1,171 @@
+/**
+ * Storage Driver - Supabase Storage API client
+ *
+ * Endpoints:
+ * - GET /storage/v1/bucket - List buckets
+ * - GET /storage/v1/object/list/{bucket} - List objects
+ * - POST /storage/v1/object/{bucket}/{path} - Upload object
+ * - GET /storage/v1/object/{bucket}/{path} - Download object
+ * - DELETE /storage/v1/object/{bucket}/{path} - Delete object
+ * - POST /storage/v1/object/move - Move object
+ * - POST /storage/v1/object/copy - Copy object
+ */
+import axios from 'axios';
+import { writeFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { createReadStream } from 'node:fs';
+export class StorageDriver {
+    client;
+    serviceRoleKey;
+    tenantId;
+    constructor(options) {
+        this.serviceRoleKey = options.serviceRoleKey;
+        this.tenantId = options.tenantId;
+        this.client = axios.create({
+            baseURL: `${options.endpoint}/storage/v1`,
+            timeout: options.timeout ?? 60000,
+            headers: {
+                'Authorization': `Bearer ${this.serviceRoleKey}`,
+                'apikey': this.serviceRoleKey,
+            },
+        });
+    }
+    getHeaders() {
+        const headers = {
+            'Authorization': `Bearer ${this.serviceRoleKey}`,
+            'apikey': this.serviceRoleKey,
+        };
+        if (this.tenantId) {
+            headers['X-Tenant-Id'] = this.tenantId;
+        }
+        return headers;
+    }
+    handleError(error) {
+        if (axios.isAxiosError(error)) {
+            const axiosError = error;
+            const status = axiosError.response?.status;
+            const data = axiosError.response?.data;
+            let message = axiosError.message;
+            if (status === 401) {
+                message = 'Authentication failed. Please check your service_role key and run "pxbaas login" again.';
+            }
+            else if (status === 403) {
+                message = 'Permission denied. Storage operations require service_role key.';
+            }
+            else if (status === 404) {
+                message = 'Object or bucket not found. Please check the path and try again.';
+            }
+            else if (data?.error) {
+                message = String(data.error);
+            }
+            else if (data?.message) {
+                message = String(data.message);
+            }
+            throw new Error(`Storage API error (${status ?? 'unknown'}): ${message}`);
+        }
+        throw error;
+    }
+    /**
+     * List all buckets
+     */
+    async listBuckets() {
+        try {
+            const response = await this.client.get('/bucket', { headers: this.getHeaders() });
+            return response.data ?? [];
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * List objects in a bucket
+     */
+    async listObjects(bucket, prefix) {
+        try {
+            const response = await this.client.post(`/object/list/${bucket}`, { prefix, limit: 1000 }, { headers: this.getHeaders() });
+            return response.data ?? [];
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Upload a file to storage
+     */
+    async upload(bucket, remotePath, localPath) {
+        try {
+            const fileStream = createReadStream(localPath);
+            const stats = await stat(localPath);
+            const filename = basename(localPath);
+            await this.client.post(`/object/${bucket}/${remotePath}`, fileStream, {
+                headers: {
+                    ...this.getHeaders(),
+                    'Content-Type': 'application/octet-stream',
+                    'Content-Length': stats.size,
+                },
+            });
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Download a file from storage
+     */
+    async download(bucket, remotePath, localPath) {
+        try {
+            const response = await this.client.get(`/object/${bucket}/${remotePath}`, {
+                headers: this.getHeaders(),
+                responseType: 'arraybuffer',
+            });
+            await writeFile(localPath, response.data);
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Delete an object from storage
+     */
+    async delete(bucket, remotePath) {
+        try {
+            await this.client.delete(`/object/${bucket}/${remotePath}`, { headers: this.getHeaders() });
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Move/rename an object
+     */
+    async move(sourceBucket, sourcePath, destBucket, destPath) {
+        try {
+            await this.client.post('/object/move', {
+                bucketId: sourceBucket,
+                sourceKey: sourcePath,
+                destinationBucket: destBucket,
+                destinationKey: destPath,
+            }, { headers: this.getHeaders() });
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    /**
+     * Copy an object
+     */
+    async copy(sourceBucket, sourcePath, destBucket, destPath) {
+        try {
+            await this.client.post('/object/copy', {
+                bucketId: sourceBucket,
+                sourceKey: sourcePath,
+                destinationBucket: destBucket,
+                destinationKey: destPath,
+            }, { headers: this.getHeaders() });
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+}
+//# sourceMappingURL=storage.driver.js.map

package/dist/drivers/storage.driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.driver.js","sourceRoot":"","sources":["../../src/drivers/storage.driver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/zero.driver.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Zero Driver — PolarDB-X Zero PXBaas provisioning client.
+ *
+ * Wraps the unauthenticated Zero API that claims a disposable, Supabase-compatible
+ * BaaS instance from a pre-warmed pool (15-day TTL, no renewal).
+ *
+ * Contract source: https://zero.polardbx.com/BAAS-SKILL.md (polardbx-zero-pxbaas v0.1.0)
+ *
+ * Endpoints:
+ * - POST   /api/v1/supabase/instances        claim (body: { whitelistIp? })
+ * - GET    /api/v1/supabase/instances         list  (needs pxz_token cookie)
+ * - DELETE /api/v1/supabase/instances/{id}    release (needs pxz_token cookie)
+ *
+ * Ownership: the claim response returns a `token` (also set as the `pxz_token`
+ * cookie). list/release must send it back via `Cookie: pxz_token=<token>`.
+ */
+import { AxiosError } from 'axios';
+export interface ZeroInstance {
+    id: string;
+    status: string;
+    region?: string;
+    zoneId?: string;
+    aliyunInstanceId?: string;
+    /** host:8000 WITHOUT scheme, e.g. "pxsp-xxxhttp.polardbxaisupabase.rds.aliyuncs.com:8000" */
+    publicEndpoint: string;
+    dashboardUrl?: string;
+    /** Canonical App origin returned by the platform; clients must not derive it. */
+    appEndpoint?: string;
+    appDomain?: {
+        hostname: string;
+        status: string;
+        tlsStatus: string;
+    };
+    apiKey: string;
+    serviceRoleKey: string;
+    dbPassword?: string;
+    dashboardPassword?: string;
+    whitelistIp?: string;
+    assignedAt?: string;
+    expiresAt?: string;
+    createdAt?: string;
+}
+export interface ZeroClaimResponse {
+    instance: ZeroInstance;
+    token: string;
+}
+export interface ZeroDriverOptions {
+    /** Zero API base URL. Defaults to https://zero.polardbx.com (override via BAAS_ZERO_ENDPOINT). */
+    baseUrl?: string;
+    timeout?: number;
+}
+/** Error codes returned by Zero (`{ error: { code, message } }`). */
+export type ZeroErrorCode = 'INVALID_WHITELIST_IP' | 'INSTANCE_NOT_FOUND' | 'RATE_LIMIT_EXCEEDED' | 'SUPABASE_LIMIT_REACHED' | 'SUPABASE_POOL_EXHAUSTED' | 'SUPABASE_DISABLED' | 'INTERNAL_ERROR' | 'NETWORK_ERROR' | 'UNKNOWN';
+export declare class ZeroError extends Error {
+    code: ZeroErrorCode;
+    status?: number;
+    constructor(code: ZeroErrorCode, message: string, status?: number);
+}
+export declare class ZeroDriver {
+    private client;
+    constructor(options?: ZeroDriverOptions);
+    /** Claim a new instance. Unauthenticated. Optionally whitelist extra IPs. */
+    claim(whitelistIp?: string): Promise<ZeroClaimResponse>;
+    /** List the caller's non-released instances. Requires the ownership token. */
+    list(token: string): Promise<ZeroInstance[]>;
+    /** Release (destroy) an instance. Requires the ownership token. */
+    release(id: string, token: string): Promise<void>;
+    /**
+     * Normalize the publicEndpoint (host:8000, no scheme) into a base URL.
+     * Prefers dashboardUrl when it already carries a scheme.
+     */
+    static toEndpoint(instance: ZeroInstance, scheme?: string): string;
+    private toError;
+    private codeFromStatus;
+}
+/** Wrap a network-level axios failure into a ZeroError. */
+export declare function isZeroNetworkError(e: unknown): e is AxiosError;
+//# sourceMappingURL=zero.driver.d.ts.map

package/dist/drivers/zero.driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero.driver.d.ts","sourceRoot":"","sources":["../../src/drivers/zero.driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAc,EAAiB,UAAU,EAAE,MAAM,OAAO,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,kGAAkG;IAClG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qEAAqE;AACrE,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,wBAAwB,GACxB,yBAAyB,GACzB,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,GACf,SAAS,CAAC;AAEd,qBAAa,SAAU,SAAQ,KAAK;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;gBACJ,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMlE;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAgB;gBAElB,OAAO,GAAE,iBAAsB;IAa3C,6EAA6E;IACvE,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAe7D,8EAA8E;IACxE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAalD,mEAAmE;IAC7D,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvD;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,GAAG,MAAM;IAQlE,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,cAAc;CAUvB;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAE9D"}

package/dist/drivers/zero.driver.js

@@ -0,0 +1,117 @@
+/**
+ * Zero Driver — PolarDB-X Zero PXBaas provisioning client.
+ *
+ * Wraps the unauthenticated Zero API that claims a disposable, Supabase-compatible
+ * BaaS instance from a pre-warmed pool (15-day TTL, no renewal).
+ *
+ * Contract source: https://zero.polardbx.com/BAAS-SKILL.md (polardbx-zero-pxbaas v0.1.0)
+ *
+ * Endpoints:
+ * - POST   /api/v1/supabase/instances        claim (body: { whitelistIp? })
+ * - GET    /api/v1/supabase/instances         list  (needs pxz_token cookie)
+ * - DELETE /api/v1/supabase/instances/{id}    release (needs pxz_token cookie)
+ *
+ * Ownership: the claim response returns a `token` (also set as the `pxz_token`
+ * cookie). list/release must send it back via `Cookie: pxz_token=<token>`.
+ */
+import axios from 'axios';
+export class ZeroError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'ZeroError';
+        this.code = code;
+        this.status = status;
+    }
+}
+const DEFAULT_BASE_URL = 'https://zero.polardbx.com';
+export class ZeroDriver {
+    client;
+    constructor(options = {}) {
+        const baseUrl = options.baseUrl ?? process.env.BAAS_ZERO_ENDPOINT ?? DEFAULT_BASE_URL;
+        this.client = axios.create({
+            baseURL: baseUrl.replace(/\/$/, ''),
+            timeout: options.timeout ?? 30000,
+            // NOTE: do NOT set a default Content-Type. axios adds application/json
+            // automatically for the claim() POST object body, but a DELETE/GET carrying
+            // Content-Type: application/json with no body makes Zero return HTTP 400.
+            // Do not throw on non-2xx; we map errors ourselves.
+            validateStatus: () => true,
+        });
+    }
+    /** Claim a new instance. Unauthenticated. Optionally whitelist extra IPs. */
+    async claim(whitelistIp) {
+        const body = {};
+        if (whitelistIp)
+            body.whitelistIp = whitelistIp;
+        const res = await this.client.post('/api/v1/supabase/instances', body);
+        if (res.status !== 200 && res.status !== 201) {
+            throw this.toError(res.status, res.data);
+        }
+        const data = res.data;
+        if (!data?.instance?.id || !data?.token) {
+            throw new ZeroError('UNKNOWN', 'Malformed claim response: missing instance.id or token', res.status);
+        }
+        return data;
+    }
+    /** List the caller's non-released instances. Requires the ownership token. */
+    async list(token) {
+        const res = await this.client.get('/api/v1/supabase/instances', {
+            headers: { Cookie: `pxz_token=${token}` },
+        });
+        if (res.status !== 200) {
+            throw this.toError(res.status, res.data);
+        }
+        const data = res.data;
+        if (Array.isArray(data))
+            return data;
+        const obj = data;
+        return obj?.instances ?? [];
+    }
+    /** Release (destroy) an instance. Requires the ownership token. */
+    async release(id, token) {
+        const res = await this.client.delete(`/api/v1/supabase/instances/${encodeURIComponent(id)}`, {
+            headers: { Cookie: `pxz_token=${token}` },
+        });
+        if (res.status !== 200 && res.status !== 204) {
+            throw this.toError(res.status, res.data);
+        }
+    }
+    /**
+     * Normalize the publicEndpoint (host:8000, no scheme) into a base URL.
+     * Prefers dashboardUrl when it already carries a scheme.
+     */
+    static toEndpoint(instance, scheme = 'http') {
+        if (instance.dashboardUrl && /^https?:\/\//.test(instance.dashboardUrl)) {
+            return instance.dashboardUrl.replace(/\/$/, '');
+        }
+        const host = instance.publicEndpoint.replace(/^https?:\/\//, '').replace(/\/$/, '');
+        return `${scheme}://${host}`;
+    }
+    toError(status, data) {
+        const err = data?.error;
+        const code = err?.code ?? this.codeFromStatus(status);
+        const message = err?.message ?? `Zero API error (HTTP ${status})`;
+        return new ZeroError(code, message, status);
+    }
+    codeFromStatus(status) {
+        if (status === 429)
+            return 'RATE_LIMIT_EXCEEDED';
+        if (status === 503)
+            return 'SUPABASE_POOL_EXHAUSTED';
+        if (status === 404)
+            return 'INSTANCE_NOT_FOUND';
+        if (status >= 500)
+            return 'INTERNAL_ERROR';
+        // 400 is not mapped to a specific code: INVALID_WHITELIST_IP is claim-only and
+        // comes from the response body's error.code (preferred in toError). A bare 400
+        // on other calls (e.g. release) must not be mislabeled as a whitelist error.
+        return 'UNKNOWN';
+    }
+}
+/** Wrap a network-level axios failure into a ZeroError. */
+export function isZeroNetworkError(e) {
+    return axios.isAxiosError(e);
+}
+//# sourceMappingURL=zero.driver.js.map

package/dist/drivers/zero.driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero.driver.js","sourceRoot":"","sources":["../../src/drivers/zero.driver.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @polardbx/pxbaas-client
+ *
+ * Shared HTTP client SDK for PolarDB-X BaaS data plane APIs.
+ *
+ * This package provides typed clients for:
+ * - Kong gateway routing
+ * - Meta API (/pg/*)
+ * - Functions Management API (/v1/projects/*)
+ * - Storage API (/storage/v1/*)
+ * - Auth Admin API (/auth/v1/admin/*)
+ * - REST API (/rest/v1/*)
+ *
+ * @packageDocumentation
+ */
+export * from "./types.js";
+export * from "./drivers/meta.driver.js";
+export * from "./drivers/functions.driver.js";
+export * from "./drivers/apps.driver.js";
+export * from "./drivers/share-links.driver.js";
+export * from "./drivers/storage.driver.js";
+export * from "./drivers/auth-admin.driver.js";
+export * from "./drivers/zero.driver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,YAAY,CAAC;AAM3B,cAAc,0BAA0B,CAAC;AAGzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,gCAAgC,CAAC;AAG/C,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * @polardbx/pxbaas-client
+ *
+ * Shared HTTP client SDK for PolarDB-X BaaS data plane APIs.
+ *
+ * This package provides typed clients for:
+ * - Kong gateway routing
+ * - Meta API (/pg/*)
+ * - Functions Management API (/v1/projects/*)
+ * - Storage API (/storage/v1/*)
+ * - Auth Admin API (/auth/v1/admin/*)
+ * - REST API (/rest/v1/*)
+ *
+ * @packageDocumentation
+ */
+export * from "./types.js";
+// TODO: M1 - Add Kong client
+// export * from './kong.js';
+// M3 - Meta API driver
+export * from "./drivers/meta.driver.js";
+// M4 - Functions, Apps, and Storage drivers
+export * from "./drivers/functions.driver.js";
+export * from "./drivers/apps.driver.js";
+export * from "./drivers/share-links.driver.js";
+export * from "./drivers/storage.driver.js";
+// M5 - Auth Admin driver
+export * from "./drivers/auth-admin.driver.js";
+// Zero provisioning driver (PolarDB-X Zero PXBaas)
+export * from "./drivers/zero.driver.js";
+// TODO: M5 - Add REST driver
+// export * from './drivers/rest.driver.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,YAAY,CAAC;AAE3B,6BAA6B;AAC7B,6BAA6B;AAE7B,uBAAuB;AACvB,cAAc,0BAA0B,CAAC;AAEzC,4CAA4C;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAE5C,yBAAyB;AACzB,cAAc,gCAAgC,CAAC;AAE/C,mDAAmD;AACnD,cAAc,0BAA0B,CAAC;AAEzC,6BAA6B;AAC7B,4CAA4C"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Core types for @polardbx/pxbaas-client
+ */
+export interface TenantProfile {
+    endpoint: string;
+    tenantId?: string;
+    anonKey: string;
+    serviceRoleKey: string;
+}
+export interface JwtPayload {
+    role: 'anon' | 'service_role';
+    tenant_id?: string;
+    iss: string;
+    iat: number;
+    exp: number;
+}
+export interface ApiResponse<T = unknown> {
+    data: T;
+    error?: string;
+}
+export interface PaginatedResponse<T> extends ApiResponse<T[]> {
+    count: number;
+    offset: number;
+    limit: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,EAAE,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core types for @polardbx/pxbaas-client
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@polardbx/pxbaas-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "Shared HTTP client SDK for PolarDB-X BaaS data plane APIs",
+  "keywords": [
+    "polardbx",
+    "baas",
+    "client",
+    "sdk",
+    "http"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polardbx/mysql-supabase.git",
+    "directory": "cli/packages/baas-client"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "msw": "^2.2.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.