@stardeck-customer-apps/data-store-sdk 0.1.0-preview.0

package/dist/server/index.d.ts

@@ -0,0 +1,108 @@
+import { D as DataStoreClientConfig, a as TableSchema, C as ColumnDefinition, b as QueryOptions, c as QueryResult, L as ListObjectsResult } from '../types-CqVD-TLQ.js';
+import { KyselyConfig, Kysely } from 'kysely';
+
+/**
+ * Data Store client for server-side use in deployed projects.
+ *
+ * Provides three capabilities:
+ * - Schema management (create/alter tables and columns)
+ * - Dynamic queries (read/write data without generated types)
+ * - Storage operations (upload/download/list files for storage-type stores)
+ *
+ * All operations go through the Stardeck platform API with HMAC authentication.
+ * For type-safe queries, use Kysely with a direct connection string instead.
+ */
+declare class DataStoreClient {
+    private baseUrl;
+    private storeId;
+    private deploymentSecret;
+    private organizationId;
+    private projectId;
+    private deploymentId;
+    private maxRetries;
+    private debug;
+    constructor(config: DataStoreClientConfig);
+    private getEnv;
+    private log;
+    private getAuthHeader;
+    private request;
+    getSchema(): Promise<{
+        tables: TableSchema[];
+    }>;
+    createTable(name: string, columns: ColumnDefinition[]): Promise<{
+        tableName: string;
+    }>;
+    addColumn(tableName: string, column: ColumnDefinition): Promise<{
+        columnName: string;
+    }>;
+    updateColumn(tableName: string, columnName: string, changes: {
+        newName?: string;
+        newType?: string;
+        currentType?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    deleteColumn(tableName: string, columnName: string): Promise<{
+        deletedAs: string;
+    }>;
+    query(tableName: string, options?: QueryOptions): Promise<QueryResult>;
+    insert(tableName: string, row: Record<string, unknown>): Promise<{
+        row: Record<string, unknown>;
+    }>;
+    update(tableName: string, primaryKey: Record<string, unknown>, column: string, value: unknown): Promise<{
+        row: Record<string, unknown>;
+    }>;
+    delete(tableName: string, primaryKey: Record<string, unknown>): Promise<{
+        deleted: boolean;
+    }>;
+    listFiles(options?: {
+        prefix?: string;
+        cursor?: string;
+    }): Promise<ListObjectsResult>;
+    getUploadUrl(key: string, contentType: string, size: number): Promise<{
+        uploadUrl: string;
+        key: string;
+    }>;
+    getDownloadUrl(key: string): Promise<{
+        downloadUrl: string;
+    }>;
+    deleteFiles(keys: string[]): Promise<{
+        deleted: number;
+    }>;
+    createFolder(path: string): Promise<{
+        key: string;
+    }>;
+}
+
+declare function signDeploymentRequest(deploymentSecret: string, payload: {
+    organizationId: string;
+    projectId: string;
+    deploymentId: string;
+}): string;
+
+/**
+ * Creates a Kysely instance for direct database access to a data store.
+ * Use this for type-safe queries when you have generated types and a connection string.
+ *
+ * Requires `@neondatabase/serverless` and `kysely-neon` as peer dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
+ * import type { DB } from "./generated/data-store-types";
+ *
+ * const db = await createDataStore<DB>();
+ *
+ * const users = await db
+ *   .selectFrom("users")
+ *   .where("status", "=", "active")
+ *   .selectAll()
+ *   .execute();
+ * ```
+ */
+declare function createDataStore<DB>(options?: {
+    connectionString?: string;
+    kyselyConfig?: Partial<KyselyConfig>;
+}): Promise<Kysely<DB>>;
+
+export { DataStoreClient, createDataStore, signDeploymentRequest };

package/dist/server/index.js

@@ -0,0 +1,265 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  DataStoreClient: () => DataStoreClient,
+  createDataStore: () => createDataStore,
+  signDeploymentRequest: () => signDeploymentRequest
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/errors.ts
+var DataStoreError = class extends Error {
+  code;
+  statusCode;
+  constructor(message, code, statusCode) {
+    super(message);
+    this.name = "DataStoreError";
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+};
+var AuthenticationError = class extends DataStoreError {
+  constructor(message = "Authentication failed") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+
+// src/server/hmac.ts
+var import_crypto = __toESM(require("crypto"));
+function signDeploymentRequest(deploymentSecret, payload) {
+  const requestPayload = {
+    type: "deployment-request",
+    organizationId: payload.organizationId,
+    projectId: payload.projectId,
+    deploymentId: payload.deploymentId,
+    timestamp: Math.floor(Date.now() / 1e3),
+    nonce: import_crypto.default.randomUUID()
+  };
+  const payloadJson = JSON.stringify(requestPayload);
+  const payloadB64 = Buffer.from(payloadJson).toString("base64");
+  const signature = import_crypto.default.createHmac("sha256", deploymentSecret).update(payloadJson).digest("hex");
+  return `${payloadB64}.${signature}`;
+}
+
+// src/server/client.ts
+var DataStoreClient = class {
+  baseUrl;
+  storeId;
+  deploymentSecret;
+  organizationId;
+  projectId;
+  deploymentId;
+  maxRetries;
+  debug;
+  constructor(config) {
+    this.storeId = config.storeId;
+    this.baseUrl = config.baseUrl || this.getEnv("CONTROL_PLANE_URL") || "";
+    this.deploymentSecret = config.deploymentSecret || this.getEnv("DEPLOYMENT_SECRET") || "";
+    this.organizationId = config.organizationId || this.getEnv("ORGANIZATION_ID") || "";
+    this.projectId = config.projectId || this.getEnv("PROJECT_ID") || "";
+    this.deploymentId = config.deploymentId || this.getEnv("DEPLOYMENT_ID") || "";
+    this.maxRetries = config.maxRetries ?? 3;
+    this.debug = config.debug ?? false;
+    if (!this.baseUrl || !this.deploymentSecret || !this.organizationId || !this.projectId || !this.deploymentId) {
+      console.warn(
+        "[DataStoreClient] Not fully configured. Set CONTROL_PLANE_URL, DEPLOYMENT_SECRET, ORGANIZATION_ID, PROJECT_ID, and DEPLOYMENT_ID environment variables."
+      );
+    }
+  }
+  getEnv(key) {
+    if (typeof process !== "undefined" && process.env?.[key]) {
+      return process.env[key];
+    }
+    return void 0;
+  }
+  log(...args) {
+    if (this.debug) {
+      console.log("[DataStoreClient]", ...args);
+    }
+  }
+  getAuthHeader() {
+    return signDeploymentRequest(this.deploymentSecret, {
+      organizationId: this.organizationId,
+      projectId: this.projectId,
+      deploymentId: this.deploymentId
+    });
+  }
+  async request(method, path, body, queryParams) {
+    let url = `${this.baseUrl}/api/data-stores/${this.storeId}${path}`;
+    if (queryParams) {
+      const params = new URLSearchParams(queryParams);
+      if (method === "GET") {
+        params.set("deploymentId", this.deploymentId);
+      }
+      url += `?${params.toString()}`;
+    } else if (method === "GET") {
+      url += `?deploymentId=${this.deploymentId}`;
+    }
+    const requestBody = method !== "GET" && body ? { ...body, deploymentId: this.deploymentId } : method !== "GET" ? { deploymentId: this.deploymentId } : void 0;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        this.log(`${method} ${path}`, { attempt });
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            "X-Stardeck-Auth": this.getAuthHeader()
+          },
+          body: requestBody ? JSON.stringify(requestBody) : void 0
+        });
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          const message = errorData.error || `HTTP ${response.status}`;
+          if (response.status === 401) {
+            throw new AuthenticationError(message);
+          }
+          throw new DataStoreError(message, "API_ERROR", response.status);
+        }
+        const data = await response.json();
+        if (data && typeof data === "object" && "success" in data && data.success && "data" in data) {
+          return data.data;
+        }
+        return data;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (error instanceof AuthenticationError) throw error;
+        if (error instanceof DataStoreError && error.statusCode < 500) throw error;
+        if (attempt < this.maxRetries) {
+          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+          await new Promise((r) => setTimeout(r, delay));
+        }
+      }
+    }
+    throw lastError ?? new DataStoreError("Request failed", "UNKNOWN", 500);
+  }
+  // ─── Schema Operations ──────────────────────────────────────
+  async getSchema() {
+    return this.request("GET", "/schema");
+  }
+  async createTable(name, columns) {
+    return this.request("POST", "/schema/tables", { name, columns });
+  }
+  async addColumn(tableName, column) {
+    return this.request("POST", "/schema/columns", { tableName, column });
+  }
+  async updateColumn(tableName, columnName, changes) {
+    return this.request("PATCH", "/schema/columns", {
+      tableName,
+      columnName,
+      ...changes
+    });
+  }
+  async deleteColumn(tableName, columnName) {
+    return this.request("DELETE", "/schema/columns", { tableName, columnName });
+  }
+  // ─── Query Operations ───────────────────────────────────────
+  async query(tableName, options = {}) {
+    return this.request("POST", "/query", {
+      tableName,
+      limit: options.limit ?? 50,
+      offset: options.offset ?? 0,
+      orderBy: options.orderBy,
+      orderDir: options.orderDir,
+      filters: options.filters ?? []
+    });
+  }
+  async insert(tableName, row) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "insert",
+      row
+    });
+  }
+  async update(tableName, primaryKey, column, value) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "update",
+      primaryKey,
+      column,
+      value
+    });
+  }
+  async delete(tableName, primaryKey) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "delete",
+      primaryKey
+    });
+  }
+  // ─── Storage Operations ─────────────────────────────────────
+  async listFiles(options) {
+    const params = {};
+    if (options?.prefix) params.prefix = options.prefix;
+    if (options?.cursor) params.cursor = options.cursor;
+    return this.request("GET", "/storage", void 0, params);
+  }
+  async getUploadUrl(key, contentType, size) {
+    return this.request("POST", "/storage/upload", { key, contentType, size });
+  }
+  async getDownloadUrl(key) {
+    return this.request("GET", "/storage/download", void 0, { key });
+  }
+  async deleteFiles(keys) {
+    return this.request("DELETE", "/storage/objects", { keys });
+  }
+  async createFolder(path) {
+    return this.request("POST", "/storage/folder", { path });
+  }
+};
+
+// src/server/kysely.ts
+var import_kysely = require("kysely");
+async function createDataStore(options) {
+  const connectionString = options?.connectionString ?? (typeof process !== "undefined" ? process.env?.DATA_STORE_URL : void 0);
+  if (!connectionString) {
+    throw new Error(
+      "DATA_STORE_URL environment variable is required, or pass connectionString in options"
+    );
+  }
+  const { Kysely: KyselyClass } = await import("kysely");
+  const { NeonDialect } = await import("kysely-neon");
+  const { neon } = await import("@neondatabase/serverless");
+  const sql = neon(connectionString);
+  const dialect = new NeonDialect({ neon: sql });
+  return new KyselyClass({
+    dialect,
+    ...options?.kyselyConfig
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataStoreClient,
+  createDataStore,
+  signDeploymentRequest
+});

package/dist/server/index.mjs

@@ -0,0 +1,213 @@
+import {
+  AuthenticationError,
+  DataStoreError
+} from "../chunk-7YN3WP4H.mjs";
+
+// src/server/hmac.ts
+import crypto from "crypto";
+function signDeploymentRequest(deploymentSecret, payload) {
+  const requestPayload = {
+    type: "deployment-request",
+    organizationId: payload.organizationId,
+    projectId: payload.projectId,
+    deploymentId: payload.deploymentId,
+    timestamp: Math.floor(Date.now() / 1e3),
+    nonce: crypto.randomUUID()
+  };
+  const payloadJson = JSON.stringify(requestPayload);
+  const payloadB64 = Buffer.from(payloadJson).toString("base64");
+  const signature = crypto.createHmac("sha256", deploymentSecret).update(payloadJson).digest("hex");
+  return `${payloadB64}.${signature}`;
+}
+
+// src/server/client.ts
+var DataStoreClient = class {
+  baseUrl;
+  storeId;
+  deploymentSecret;
+  organizationId;
+  projectId;
+  deploymentId;
+  maxRetries;
+  debug;
+  constructor(config) {
+    this.storeId = config.storeId;
+    this.baseUrl = config.baseUrl || this.getEnv("CONTROL_PLANE_URL") || "";
+    this.deploymentSecret = config.deploymentSecret || this.getEnv("DEPLOYMENT_SECRET") || "";
+    this.organizationId = config.organizationId || this.getEnv("ORGANIZATION_ID") || "";
+    this.projectId = config.projectId || this.getEnv("PROJECT_ID") || "";
+    this.deploymentId = config.deploymentId || this.getEnv("DEPLOYMENT_ID") || "";
+    this.maxRetries = config.maxRetries ?? 3;
+    this.debug = config.debug ?? false;
+    if (!this.baseUrl || !this.deploymentSecret || !this.organizationId || !this.projectId || !this.deploymentId) {
+      console.warn(
+        "[DataStoreClient] Not fully configured. Set CONTROL_PLANE_URL, DEPLOYMENT_SECRET, ORGANIZATION_ID, PROJECT_ID, and DEPLOYMENT_ID environment variables."
+      );
+    }
+  }
+  getEnv(key) {
+    if (typeof process !== "undefined" && process.env?.[key]) {
+      return process.env[key];
+    }
+    return void 0;
+  }
+  log(...args) {
+    if (this.debug) {
+      console.log("[DataStoreClient]", ...args);
+    }
+  }
+  getAuthHeader() {
+    return signDeploymentRequest(this.deploymentSecret, {
+      organizationId: this.organizationId,
+      projectId: this.projectId,
+      deploymentId: this.deploymentId
+    });
+  }
+  async request(method, path, body, queryParams) {
+    let url = `${this.baseUrl}/api/data-stores/${this.storeId}${path}`;
+    if (queryParams) {
+      const params = new URLSearchParams(queryParams);
+      if (method === "GET") {
+        params.set("deploymentId", this.deploymentId);
+      }
+      url += `?${params.toString()}`;
+    } else if (method === "GET") {
+      url += `?deploymentId=${this.deploymentId}`;
+    }
+    const requestBody = method !== "GET" && body ? { ...body, deploymentId: this.deploymentId } : method !== "GET" ? { deploymentId: this.deploymentId } : void 0;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        this.log(`${method} ${path}`, { attempt });
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            "X-Stardeck-Auth": this.getAuthHeader()
+          },
+          body: requestBody ? JSON.stringify(requestBody) : void 0
+        });
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          const message = errorData.error || `HTTP ${response.status}`;
+          if (response.status === 401) {
+            throw new AuthenticationError(message);
+          }
+          throw new DataStoreError(message, "API_ERROR", response.status);
+        }
+        const data = await response.json();
+        if (data && typeof data === "object" && "success" in data && data.success && "data" in data) {
+          return data.data;
+        }
+        return data;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (error instanceof AuthenticationError) throw error;
+        if (error instanceof DataStoreError && error.statusCode < 500) throw error;
+        if (attempt < this.maxRetries) {
+          const delay = Math.min(1e3 * 2 ** attempt, 1e4);
+          await new Promise((r) => setTimeout(r, delay));
+        }
+      }
+    }
+    throw lastError ?? new DataStoreError("Request failed", "UNKNOWN", 500);
+  }
+  // ─── Schema Operations ──────────────────────────────────────
+  async getSchema() {
+    return this.request("GET", "/schema");
+  }
+  async createTable(name, columns) {
+    return this.request("POST", "/schema/tables", { name, columns });
+  }
+  async addColumn(tableName, column) {
+    return this.request("POST", "/schema/columns", { tableName, column });
+  }
+  async updateColumn(tableName, columnName, changes) {
+    return this.request("PATCH", "/schema/columns", {
+      tableName,
+      columnName,
+      ...changes
+    });
+  }
+  async deleteColumn(tableName, columnName) {
+    return this.request("DELETE", "/schema/columns", { tableName, columnName });
+  }
+  // ─── Query Operations ───────────────────────────────────────
+  async query(tableName, options = {}) {
+    return this.request("POST", "/query", {
+      tableName,
+      limit: options.limit ?? 50,
+      offset: options.offset ?? 0,
+      orderBy: options.orderBy,
+      orderDir: options.orderDir,
+      filters: options.filters ?? []
+    });
+  }
+  async insert(tableName, row) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "insert",
+      row
+    });
+  }
+  async update(tableName, primaryKey, column, value) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "update",
+      primaryKey,
+      column,
+      value
+    });
+  }
+  async delete(tableName, primaryKey) {
+    return this.request("POST", "/mutate", {
+      tableName,
+      operation: "delete",
+      primaryKey
+    });
+  }
+  // ─── Storage Operations ─────────────────────────────────────
+  async listFiles(options) {
+    const params = {};
+    if (options?.prefix) params.prefix = options.prefix;
+    if (options?.cursor) params.cursor = options.cursor;
+    return this.request("GET", "/storage", void 0, params);
+  }
+  async getUploadUrl(key, contentType, size) {
+    return this.request("POST", "/storage/upload", { key, contentType, size });
+  }
+  async getDownloadUrl(key) {
+    return this.request("GET", "/storage/download", void 0, { key });
+  }
+  async deleteFiles(keys) {
+    return this.request("DELETE", "/storage/objects", { keys });
+  }
+  async createFolder(path) {
+    return this.request("POST", "/storage/folder", { path });
+  }
+};
+
+// src/server/kysely.ts
+import "kysely";
+async function createDataStore(options) {
+  const connectionString = options?.connectionString ?? (typeof process !== "undefined" ? process.env?.DATA_STORE_URL : void 0);
+  if (!connectionString) {
+    throw new Error(
+      "DATA_STORE_URL environment variable is required, or pass connectionString in options"
+    );
+  }
+  const { Kysely: KyselyClass } = await import("kysely");
+  const { NeonDialect } = await import("kysely-neon");
+  const { neon } = await import("@neondatabase/serverless");
+  const sql = neon(connectionString);
+  const dialect = new NeonDialect({ neon: sql });
+  return new KyselyClass({
+    dialect,
+    ...options?.kyselyConfig
+  });
+}
+export {
+  DataStoreClient,
+  createDataStore,
+  signDeploymentRequest
+};

package/dist/types-CqVD-TLQ.d.mts

@@ -0,0 +1,68 @@
+interface DataStoreClientConfig {
+    /** Stardeck platform API base URL (default: CONTROL_PLANE_URL env var) */
+    baseUrl?: string;
+    storeId: string;
+    /** HMAC signing secret (default: DEPLOYMENT_SECRET env var) */
+    deploymentSecret?: string;
+    organizationId?: string;
+    projectId?: string;
+    deploymentId?: string;
+    maxRetries?: number;
+    debug?: boolean;
+}
+interface ColumnDefinition {
+    name: string;
+    fieldType: string;
+    nullable?: boolean;
+    displayName?: string;
+    config?: Record<string, unknown>;
+}
+interface TableColumn {
+    columnName: string;
+    dataType: string;
+    isNullable: boolean;
+    columnDefault: string | null;
+    isPrimaryKey: boolean;
+    displayName?: string;
+    fieldType?: string;
+    fieldConfig?: Record<string, unknown> | null;
+    position?: number;
+}
+interface TableSchema {
+    tableName: string;
+    columns: TableColumn[];
+}
+type FilterOperator = "eq" | "neq" | "contains" | "gt" | "lt" | "is_null" | "is_not_null";
+interface QueryFilter {
+    column: string;
+    operator: FilterOperator;
+    value?: unknown;
+}
+interface QueryOptions {
+    filters?: QueryFilter[];
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    limit?: number;
+    offset?: number;
+}
+interface QueryResult {
+    rows: Record<string, unknown>[];
+    columns: string[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface StorageObject {
+    key: string;
+    size: number;
+    lastModified: string;
+    contentType?: string;
+}
+interface ListObjectsResult {
+    objects: StorageObject[];
+    folders: string[];
+    cursor?: string;
+    hasMore: boolean;
+}
+
+export type { ColumnDefinition as C, DataStoreClientConfig as D, FilterOperator as F, ListObjectsResult as L, QueryFilter as Q, StorageObject as S, TableColumn as T, TableSchema as a, QueryOptions as b, QueryResult as c };