@stardeck-customer-apps/data-store-sdk 0.3.0 → 0.3.1

package/SKILL.md

@@ -228,6 +228,36 @@ the schema snapshot is what `@stardeck-customer-apps/testing` applies to its
 in-process Postgres, so a stale snapshot means tests run against the wrong
 schema.
 
+> **Never hand-edit a generated file.** `data-store-types.ts` is a write-only
+> output: it's overwritten in full on every regeneration and contains only the
+> raw table interfaces plus the `DB` type. Any type you append to it is silently
+> wiped the next time the schema changes and you re-run `generate-types`.
+
+App-level / derived types — serialized shapes (`Date` → `string` for API
+responses), typed `jsonb` columns, computed/virtual fields, composite view
+models — belong in a **separate hand-written file** that imports from the
+generated one. This keeps regeneration safe and your types permanent:
+
+```typescript
+// src/lib/order-types.ts  (hand-written — survives every regeneration)
+import type { Selectable } from "kysely";
+import type { DB } from "@/generated/data-store-types";
+
+type OrderRow = Selectable<DB["orders"]>;
+
+// API-serialized shape: Dates become strings, jsonb gets a real type,
+// and we add a computed field the table doesn't store.
+export type Order = Omit<OrderRow, "created_at" | "metadata"> & {
+  created_at: string;
+  metadata: { source: string; tags: string[] };
+  is_overdue: boolean;
+};
+```
+
+If you find hand-written types already living inside a generated file, move them
+into a sibling file like this and update the imports across the codebase rather
+than perpetuating the append-and-restore cycle.
+
 ### Initialize
 
 ```typescript

package/package.json

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