@stardeck-customer-apps/data-store-sdk 0.1.0-preview.1 → 0.1.0-preview.3

package/SKILL.md

@@ -0,0 +1,295 @@
+# Data Store SDK - AI Agent Skill Guide
+
+This guide helps AI agents understand and implement data store features using `@stardeck-customer-apps/data-store-sdk`.
+
+## Quick Reference
+
+**Package**: `@stardeck-customer-apps/data-store-sdk`
+
+**Exports**:
+
+- Core: `@stardeck-customer-apps/data-store-sdk` - Types and error classes
+- Server: `@stardeck-customer-apps/data-store-sdk/server` - DataStoreClient, Kysely wrapper, HMAC signing
+
+**Two Access Patterns**:
+
+1. **createDataStore()** (Recommended) — Direct Kysely connection for type-safe queries with compile-time checking. Use this for all application CRUD.
+2. **DataStoreClient** — Platform API client for schema management, dynamic queries, and storage file operations. Use this for DDL, agent-driven access, and storage-type data stores.
+
+## Architecture Overview
+
+**Type-Safe Queries (Direct Connection — Recommended for database stores):**
+
+```
+Server Code
+    ↓ (Kysely with DATA_STORE_{NAME}_URL)
+Data Store Neon Database (direct connection)
+```
+
+`DATA_STORE_{NAME}_URL` is automatically injected in all environments (production, preview, sandbox).
+
+**Schema Management (via Platform API):**
+
+```
+Server Code
+    ↓ (DataStoreClient with HMAC auth)
+Platform API (/api/data-stores/{storeId}/schema/*)
+    ↓
+Data Store Neon Database (DDL applied)
+```
+
+**Dynamic Queries (via Platform API):**
+
+```
+Server Code
+    ↓ (DataStoreClient with HMAC auth)
+Platform API (/api/data-stores/{storeId}/query or /mutate)
+    ↓
+Data Store Neon Database
+```
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install @stardeck-customer-apps/data-store-sdk
+# For direct Kysely access (recommended for database stores):
+npm install kysely kysely-neon @neondatabase/serverless
+```
+
+### 2. Environment Variables
+
+These are automatically injected by the platform at deploy time:
+
+```bash
+CONTROL_PLANE_URL=https://app.stardeck.ai   # Platform API URL
+DEPLOYMENT_SECRET=your-secret-key            # HMAC signing (NEVER expose to client)
+ORGANIZATION_ID=org_123
+PROJECT_ID=proj_456
+DEPLOYMENT_ID=deploy_789
+DATA_STORE_MYSTORE_URL=postgres://...        # Per-store connection string (for Kysely)
+DATA_STORE_MYSTORE_ID=ds-abc123              # Per-store ID (for DataStoreClient)
+```
+
+## Pattern 1: DataStoreClient (Dynamic Queries)
+
+Use this for schema operations, agent-driven data access, or when you don't have generated types.
+
+### Initialize
+
+```typescript
+// lib/data-store.ts (server-only)
+import { DataStoreClient } from "@stardeck-customer-apps/data-store-sdk/server";
+
+export const dataStore = new DataStoreClient({
+  storeId: process.env.DATA_STORE_MYSTORE_ID!,
+  // Other config read from env vars automatically
+});
+```
+
+### Schema Operations
+
+```typescript
+// Create a table
+await dataStore.createTable("orders", [
+  { name: "customer_name", fieldType: "text" },
+  { name: "total", fieldType: "currency", config: { currency: "USD" } },
+  { name: "status", fieldType: "select", config: { options: ["pending", "shipped", "delivered"] } },
+  { name: "notes", fieldType: "long_text", nullable: true },
+]);
+
+// Add a column to an existing table
+await dataStore.addColumn("orders", {
+  name: "priority",
+  fieldType: "rating",
+  config: { max: 5 },
+});
+
+// Read schema
+const { tables } = await dataStore.getSchema();
+```
+
+### Available Field Types
+
+| Field Type     | Postgres Type | Config Options                                    |
+| -------------- | ------------- | ------------------------------------------------- |
+| `text`         | text          | —                                                 |
+| `long_text`    | text          | —                                                 |
+| `number`       | numeric       | —                                                 |
+| `boolean`      | boolean       | —                                                 |
+| `date`         | date          | —                                                 |
+| `datetime`     | timestamptz   | —                                                 |
+| `select`       | text          | `{ options: string[] }`                           |
+| `multi_select` | text[]        | `{ options: string[] }`                           |
+| `currency`     | numeric       | `{ currency: string }`                            |
+| `email`        | text          | —                                                 |
+| `phone`        | text          | —                                                 |
+| `url`          | text          | —                                                 |
+| `rating`       | integer       | `{ max: number }`                                 |
+| `relation`     | uuid          | `{ targetTable: string, displayColumn?: string }` |
+| `file_ref`     | text          | —                                                 |
+| `json`         | jsonb         | —                                                 |
+
+### Query Data
+
+```typescript
+// Simple query
+const { rows, total } = await dataStore.query("orders", {
+  filters: [
+    { column: "status", operator: "eq", value: "pending" },
+  ],
+  orderBy: "created_at",
+  orderDir: "desc",
+  limit: 20,
+});
+
+// Available filter operators: eq, neq, gt, lt, contains, is_null, is_not_null
+```
+
+### Mutate Data
+
+```typescript
+// Insert
+const { row } = await dataStore.insert("orders", {
+  customer_name: "Alice",
+  total: 99.99,
+  status: "pending",
+});
+
+// Update (by primary key)
+await dataStore.update("orders", { id: row.id }, "status", "shipped");
+
+// Delete (by primary key)
+await dataStore.delete("orders", { id: row.id });
+```
+
+### Storage Operations (for storage-type data stores)
+
+> **Not the Storage SDK.** Storage-type data stores are org-level shared file storage accessed via `DataStoreClient` (this SDK). They are a completely separate system from the legacy Storage SDK (`@stardeck-customer-apps/storage-sdk`). Do not confuse the two:
+>
+> - **Storage SDK (legacy)** = project-scoped file storage for a single app. Being phased out in favor of storage-type data stores.
+> - **Data Store storage** = org-scoped shared file storage accessed by multiple projects via `DataStoreClient`. This is the recommended approach for file storage.
+>
+> Always prefer data store storage over the Storage SDK for new code.
+
+```typescript
+// List files
+const { objects, folders } = await dataStore.listFiles({ prefix: "invoices/" });
+
+// Get upload URL (client uploads directly to R2)
+const { uploadUrl } = await dataStore.getUploadUrl("invoices/march.pdf", "application/pdf", fileSize);
+
+// Get download URL
+const { downloadUrl } = await dataStore.getDownloadUrl("invoices/march.pdf");
+
+// Delete files
+await dataStore.deleteFiles(["invoices/old.pdf"]);
+```
+
+## Pattern 2: Kysely (Type-Safe Queries)
+
+Use this for application code where you want compile-time type safety.
+
+### Generate Types
+
+```bash
+npx stardeck-data-store generate-types --connection-string $DATA_STORE_MYSTORE_URL
+# Outputs: ./src/generated/data-store-types.ts
+```
+
+### Initialize
+
+```typescript
+// lib/db.ts (server-only)
+import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
+import type { DB } from "@/generated/data-store-types";
+
+// storeName auto-reads DATA_STORE_MYSTORE_URL from env
+export const db = await createDataStore<DB>({ storeName: "mystore" });
+```
+
+### Query with Full Type Safety
+
+```typescript
+import { db } from "@/lib/db";
+
+// Select with type inference
+const orders = await db
+  .selectFrom("orders")
+  .where("status", "=", "pending")
+  .orderBy("created_at", "desc")
+  .selectAll()
+  .execute();
+
+// Insert
+const newOrder = await db
+  .insertInto("orders")
+  .values({
+    customer_name: "Bob",
+    total: 149.99,
+    status: "pending",
+  })
+  .returningAll()
+  .executeTakeFirstOrThrow();
+
+// Update
+await db
+  .updateTable("orders")
+  .set({ status: "shipped" })
+  .where("id", "=", orderId)
+  .execute();
+
+// Join
+const ordersWithCustomers = await db
+  .selectFrom("orders")
+  .innerJoin("customers", "customers.id", "orders.customer_id")
+  .select(["orders.id", "orders.total", "customers.name"])
+  .execute();
+```
+
+## Error Handling
+
+```typescript
+import {
+  DataStoreError,
+  AuthenticationError,
+  ForbiddenError,
+  ValidationError,
+  NotFoundError,
+} from "@stardeck-customer-apps/data-store-sdk";
+
+try {
+  await dataStore.query("orders");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // HMAC signature invalid or expired
+  } else if (error instanceof ForbiddenError) {
+    // Insufficient access level for this operation
+  } else if (error instanceof ValidationError) {
+    // Invalid request (bad table name, invalid filter, etc.)
+  } else if (error instanceof NotFoundError) {
+    // Data store or table not found
+  } else if (error instanceof DataStoreError) {
+    // General API error — check error.code and error.statusCode
+  }
+}
+```
+
+## When to Use Which Pattern
+
+| Scenario                                  | Pattern                     |
+| ----------------------------------------- | --------------------------- |
+| Application CRUD with known schema        | Kysely (recommended)        |
+| Complex queries (joins, CTEs, subqueries) | Kysely                      |
+| Edge functions / serverless               | Kysely                      |
+| Agent building features dynamically       | DataStoreClient             |
+| Schema management (create/alter tables)   | DataStoreClient             |
+| Storage file operations                   | DataStoreClient             |
+
+## Important Notes
+
+- **DEPLOYMENT_SECRET must never be exposed to the client.** All data store operations must happen server-side.
+- **Tables auto-generate** `id` (UUID), `created_at`, and `updated_at` columns. Don't include these in create table definitions.
+- **Column deletes are soft-deletes.** The column is renamed to `_deleted_{name}_{timestamp}` and can be restored.
+- **Type changes are restricted** to safe widening conversions (e.g., integer → bigint, boolean → text).

package/dist/server/index.d.mts

@@ -91,6 +91,13 @@ declare function signDeploymentRequest(deploymentSecret: string, payload: {
  * import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
  * import type { DB } from "./generated/data-store-types";
  *
+ * // Option 1: Use storeName to auto-read DATA_STORE_MYSTORE_URL from env
+ * const db = await createDataStore<DB>({ storeName: "mystore" });
+ *
+ * // Option 2: Pass connection string directly
+ * const db = await createDataStore<DB>({ connectionString: process.env.DATA_STORE_MYSTORE_URL });
+ *
+ * // Option 3: Falls back to DATA_STORE_URL env var
  * const db = await createDataStore<DB>();
  *
  * const users = await db
@@ -102,6 +109,7 @@ declare function signDeploymentRequest(deploymentSecret: string, payload: {
  */
 declare function createDataStore<DB>(options?: {
     connectionString?: string;
+    storeName?: string;
     kyselyConfig?: Partial<KyselyConfig>;
 }): Promise<Kysely<DB>>;
 

package/dist/server/index.d.ts

@@ -91,6 +91,13 @@ declare function signDeploymentRequest(deploymentSecret: string, payload: {
  * import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
  * import type { DB } from "./generated/data-store-types";
  *
+ * // Option 1: Use storeName to auto-read DATA_STORE_MYSTORE_URL from env
+ * const db = await createDataStore<DB>({ storeName: "mystore" });
+ *
+ * // Option 2: Pass connection string directly
+ * const db = await createDataStore<DB>({ connectionString: process.env.DATA_STORE_MYSTORE_URL });
+ *
+ * // Option 3: Falls back to DATA_STORE_URL env var
  * const db = await createDataStore<DB>();
  *
  * const users = await db
@@ -102,6 +109,7 @@ declare function signDeploymentRequest(deploymentSecret: string, payload: {
  */
 declare function createDataStore<DB>(options?: {
     connectionString?: string;
+    storeName?: string;
     kyselyConfig?: Partial<KyselyConfig>;
 }): Promise<Kysely<DB>>;
 

package/dist/server/index.js

@@ -247,10 +247,11 @@ var DataStoreClient = class {
 // 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);
+  const connectionString = options?.connectionString ?? (typeof process !== "undefined" && options?.storeName ? process.env?.[`DATA_STORE_${options.storeName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL`] : void 0) ?? (typeof process !== "undefined" ? process.env?.DATA_STORE_URL : void 0);
   if (!connectionString) {
+    const envHint = options?.storeName ? `DATA_STORE_${options.storeName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL` : "DATA_STORE_URL";
     throw new Error(
-      "DATA_STORE_URL environment variable is required, or pass connectionString in options"
+      `${envHint} environment variable is required, or pass connectionString in options`
     );
   }
   const { Kysely: KyselyClass } = await import("kysely");

package/dist/server/index.mjs

@@ -196,10 +196,11 @@ var DataStoreClient = class {
 // src/server/kysely.ts
 import "kysely";
 async function createDataStore(options) {
-  const connectionString = options?.connectionString ?? (typeof process !== "undefined" ? process.env?.DATA_STORE_URL : void 0);
+  const connectionString = options?.connectionString ?? (typeof process !== "undefined" && options?.storeName ? process.env?.[`DATA_STORE_${options.storeName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL`] : void 0) ?? (typeof process !== "undefined" ? process.env?.DATA_STORE_URL : void 0);
   if (!connectionString) {
+    const envHint = options?.storeName ? `DATA_STORE_${options.storeName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL` : "DATA_STORE_URL";
     throw new Error(
-      "DATA_STORE_URL environment variable is required, or pass connectionString in options"
+      `${envHint} environment variable is required, or pass connectionString in options`
     );
   }
   const { Kysely: KyselyClass } = await import("kysely");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/data-store-sdk",
-  "version": "0.1.0-preview.1",
+  "version": "0.1.0-preview.3",
   "description": "SDK for accessing Stardeck data stores from deployed projects",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,8 @@
     "stardeck-data-store": "./dist/cli/generate-types.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "exports": {
     ".": {