@stardeck-customer-apps/data-store-sdk 0.1.0-preview.2 → 0.1.0-preview.4

package/SKILL.md

@@ -13,11 +13,21 @@ This guide helps AI agents understand and implement data store features using `@
 
 **Two Access Patterns**:
 
-1. **DataStoreClient** — Platform API client for schema management and dynamic queries (no generated types needed)
-2. **createDataStore()** — Direct Kysely connection for type-safe queries (requires generated types + DATA_STORE_URL)
+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):**
 
 ```
@@ -38,21 +48,13 @@ Platform API (/api/data-stores/{storeId}/query or /mutate)
 Data Store Neon Database
 ```
 
-**Type-Safe Queries (Direct Connection):**
-
-```
-Server Code
-    ↓ (Kysely with DATA_STORE_URL)
-Data Store Neon Database (direct connection)
-```
-
 ## Setup
 
 ### 1. Install Dependencies
 
 ```bash
 npm install @stardeck-customer-apps/data-store-sdk
-# For direct Kysely access (optional):
+# For direct Kysely access (recommended for database stores):
 npm install kysely kysely-neon @neondatabase/serverless
 ```
 
@@ -203,9 +205,8 @@ npx stardeck-data-store generate-types --connection-string $DATA_STORE_MYSTORE_U
 import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
 import type { DB } from "@/generated/data-store-types";
 
-export const db = await createDataStore<DB>({
-  connectionString: process.env.DATA_STORE_MYSTORE_URL,
-});
+// storeName auto-reads DATA_STORE_MYSTORE_URL from env
+export const db = await createDataStore<DB>({ storeName: "mystore" });
 ```
 
 ### Query with Full Type Safety
@@ -277,14 +278,14 @@ try {
 
 ## When to Use Which Pattern
 
-| Scenario                                  | Pattern            |
-| ----------------------------------------- | ------------------ |
-| Application CRUD with known schema        | Kysely (type-safe) |
-| Agent building features dynamically       | DataStoreClient    |
-| Schema management (create/alter tables)   | DataStoreClient    |
-| Edge functions / serverless               | DataStoreClient    |
-| Complex queries (joins, CTEs, subqueries) | Kysely             |
-| Storage file operations                   | DataStoreClient    |
+| 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
 

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,16 +247,24 @@ 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");
   const { NeonDialect } = await import("kysely-neon");
-  const { neon } = await import("@neondatabase/serverless");
-  const sql = neon(connectionString);
+  const { neon, types } = await import("@neondatabase/serverless");
+  const customTypes = {
+    ...types,
+    getTypeParser: ((oid, format) => {
+      if (oid === 1700) return (val) => parseFloat(val);
+      return types.getTypeParser(oid, format);
+    })
+  };
+  const sql = neon(connectionString, { types: customTypes });
   const dialect = new NeonDialect({ neon: sql });
   return new KyselyClass({
     dialect,

package/dist/server/index.mjs

@@ -196,16 +196,24 @@ 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");
   const { NeonDialect } = await import("kysely-neon");
-  const { neon } = await import("@neondatabase/serverless");
-  const sql = neon(connectionString);
+  const { neon, types } = await import("@neondatabase/serverless");
+  const customTypes = {
+    ...types,
+    getTypeParser: ((oid, format) => {
+      if (oid === 1700) return (val) => parseFloat(val);
+      return types.getTypeParser(oid, format);
+    })
+  };
+  const sql = neon(connectionString, { types: customTypes });
   const dialect = new NeonDialect({ neon: sql });
   return new KyselyClass({
     dialect,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/data-store-sdk",
-  "version": "0.1.0-preview.2",
+  "version": "0.1.0-preview.4",
   "description": "SDK for accessing Stardeck data stores from deployed projects",
   "main": "dist/index.js",
   "module": "dist/index.mjs",