@quickscores/chat 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# QuickScores Chat Service
+
+Supabase-backed chat for QuickScores. Consumers: React Native (Android/iOS) and web app.
+
+## What’s in this repo
+
+- **Supabase**: config, migrations, and Edge Functions for chat (DB, RLS, Realtime).
+- **Shared types**: TypeScript types and Zod schemas in `src/types/` for use by RN and web clients.
+
+## Prerequisites
+
+- [Supabase CLI](https://supabase.com/docs/guides/cli) (`npm i -g supabase` or `npx supabase`)
+- Node.js 20+
+- A [Supabase project](https://supabase.com/dashboard) (for remote; optional for local-only)
+
+## Setup
+
+```bash
+npm install
+```
+
+### Local Supabase (optional)
+
+```bash
+npx supabase start
+```
+
+Use the printed URLs for local API, Studio, and DB. Link to a remote project when ready:
+
+```bash
+npx supabase link --project-ref <your-project-ref>
+```
+
+### Migrations
+
+- Create: put SQL in `supabase/migrations/` with timestamped names (e.g. `20240202120000_create_chat_tables.sql`), or use `npm run db:diff` after changing schema locally.
+- Apply locally: `npx supabase db reset` (reset + seed) or run migrations manually.
+- Push to remote: `npm run db:migrate` (or `npx supabase db push`).
+
+### Deploy to Supabase
+
+1. **Create a project** at [supabase.com/dashboard](https://supabase.com/dashboard) if you don’t have one. Note the **Project ref** (in Settings → General).
+
+2. **Link** the repo to that project (one-time):
+   ```bash
+   npx supabase link --project-ref <your-project-ref>
+   ```
+   Use your database password when prompted (from Dashboard → Settings → Database).
+
+3. **Push migrations** (schema + RLS):
+   ```bash
+   npm run db:migrate
+   ```
+   or `npx supabase db push`.
+
+4. **Deploy Edge Functions** (chat REST API):
+   ```bash
+   npx supabase functions deploy
+   ```
+   This deploys all functions in `supabase/functions/` (e.g. `chat-thread`, `chat-send-message`, `chat-mark-read`). To deploy a single function: `npx supabase functions deploy chat-thread`.
+
+5. **Set secrets** (if your functions need them): in Dashboard → Edge Functions → Secrets, or:
+   ```bash
+   npx supabase secrets set SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
+   ```
+   The hosted project already has `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` set by default for deployed functions; you only need to add custom secrets.
+
+Your API base URL will be `https://<project-ref>.supabase.co/functions/v1`. Use that in clients instead of `http://127.0.0.1:54321/functions/v1`.
+
+## Scripts
+
+| Script          | Description                          |
+|-----------------|--------------------------------------|
+| `npm run db:start`  | Start local Supabase stack           |
+| `npm run db:stop`   | Stop local Supabase                  |
+| `npm run db:reset`  | Reset DB and run migrations + seed   |
+| `npm run db:migrate`| Push migrations to linked project    |
+| `npm run db:diff`   | Generate migration from schema diff  |
+| `npm run build`       | Build types package to `dist/` (for publish) |
+| `npm run types:check` | TypeScript check (no emit)        |
+| `npm run lint`      | Prettier check                       |
+| `npm run lint:fix`  | Prettier fix                         |
+
+## Using shared types in the app
+
+From the React Native (or web) app:
+
+1. **Workspace / link** (if in a monorepo or same parent repo):
+   - Add in the app’s `package.json`: `"@quickscores/chat": "file:../chat"` (or your path).
+   - In this repo, run `npm run build` so `dist/` is present (the package entry point is the built output).
+   - Then: `import { threadSchema, type Thread, type Message, type ThreadListRow } from "@quickscores/chat";`
+   - REST request/response types: `CreateThreadBody`, `SendMessageBody`, `ThreadResponse`, `MessageResponse`, `ErrorResponse`, etc. (see `src/types/api.ts`).
+2. **From a registry**: Publish the types package (see below), then add `"@quickscores/chat": "^0.1.0"` and run `npm install`.
+
+Types are aligned with the Supabase schema and [docs/api-chat.md](docs/api-chat.md): `Thread` (chat_threads), `Message` (chat_messages), `ThreadListRow` (chat_thread_list view).
+
+### Publishing the types package to a registry
+
+The entire `src/` tree is built to `dist/` and only `dist/` is published (`"files": ["dist"]`). Supabase config, migrations, Edge Functions, scripts, and docs are not included in the tarball.
+
+1. **Build**: `npm run build` (or it runs automatically via `prepublishOnly` when you publish).
+2. **Allow publishing**: In `package.json`, set `"private": false` (or remove the `"private"` field).
+3. **Publish to npm** (see [Publishing to npm](#publishing-to-npm) below).
+
+Consumers then install with `"@quickscores/chat": "^0.1.0"` and import as before; they get types and Zod runtime from the published tarball only.
+
+#### Publishing to npm
+
+1. **Create the scope** (one-time): [npmjs.com/org/create](https://www.npmjs.com/org/create) and create the `quickscores` org (or use an existing org that will own the package).
+
+2. **Log in** (if you aren’t already):
+   ```bash
+   npm login
+   ```
+
+3. **Allow publishing**: In `package.json`, set `"private": false` (or remove the `"private"` field).
+
+4. **Publish** (build runs automatically via `prepublishOnly`):
+   ```bash
+   npm publish --access public
+   ```
+   Scoped packages (`@quickscores/chat`) are private by default; `--access public` makes them installable by anyone without a paid plan.
+
+After that, anyone can run `npm install @quickscores/chat` with no extra config or tokens.
+
+## Project layout
+
+```
+chat/
+├── supabase/
+│   ├── config.toml       # Local Supabase config
+│   ├── migrations/       # SQL migrations (chat tables, RLS)
+│   ├── functions/        # Edge Functions (chat REST API)
+│   └── seed.sql          # Optional seed data
+├── src/
+│   └── types/            # Shared TypeScript + Zod (Thread, Message, ThreadListRow, REST API types)
+├── docs/
+│   ├── prd/              # Product requirements
+│   └── api-chat.md       # Chat REST API reference
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Chat REST API
+
+We do **not** use Postgres RPCs for chat. The API is implemented as **REST HTTP endpoints** using Supabase Edge Functions: each action (get/create thread, send message, mark read) is a separate Edge Function. Clients use normal HTTP (e.g. `fetch` or `axios`).
+
+- **Docs:** [docs/api-chat.md](docs/api-chat.md)
+- **Endpoints:** `POST /functions/v1/chat-thread` (get/create thread), `chat-league-room`, `chat-team-room`, `chat-send-message`, `chat-mark-read`
+- **Auth:** Not enforced yet; use header `X-User-Id` (or body `user_id`) to identify the caller. Add JWT auth later.
+
+Run locally: `npx supabase start` then `npx supabase functions serve`. See [docs/api-chat.md](docs/api-chat.md#testing) for how to test (curl examples and `npm run test:api`).
+
+## Next steps
+
+1. Add auth: validate JWT in Edge Functions and use `auth.uid()` instead of `X-User-Id`.
+2. In the RN/app, call the chat endpoints and use types from `@quickscores/chat` (see [docs/api-chat.md](docs/api-chat.md)).

package/dist/types/api.d.ts

@@ -0,0 +1,64 @@
+import type { Message } from "./message";
+import type { Thread } from "./thread";
+/**
+ * Error response – all error responses use this shape.
+ */
+export interface ErrorResponse {
+    error: string;
+}
+/**
+ * POST /chat-thread
+ * participant_ids are QuickScores user ids (numbers).
+ */
+export interface CreateThreadBody {
+    participant_ids: number[];
+    title?: string | null;
+}
+/**
+ * POST /chat-league-room
+ */
+export interface LeagueRoomBody {
+    league_id: number;
+}
+/**
+ * POST /chat-team-room
+ */
+export interface TeamRoomBody {
+    team_id: number;
+}
+/**
+ * POST /chat-send-message
+ */
+export interface SendMessageBody {
+    thread_id: string;
+    type: string;
+    body?: string | null;
+    payload?: Record<string, unknown>;
+    client_nonce?: string | null;
+}
+/**
+ * POST /chat-mark-read
+ */
+export interface MarkReadBody {
+    thread_id: string;
+    last_read_message_id: string | null;
+}
+/**
+ * Response: get-or-create thread (chat-thread, chat-league-room, chat-team-room)
+ */
+export interface ThreadResponse {
+    thread: Thread;
+}
+/**
+ * Response: send message (chat-send-message)
+ */
+export interface MessageResponse {
+    message: Message;
+}
+/**
+ * Response: mark read (chat-mark-read)
+ */
+export interface MarkReadResponse {
+    ok: true;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/types/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/types/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,IAAI,CAAC;CACV"}

package/dist/types/api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared chat types and Zod schemas for QuickScores clients (RN, web).
+ * Kept in sync with Supabase migrations and docs/api-chat.md.
+ */
+export { threadKindSchema, threadSchema, threadListRowSchema, type Thread, type ThreadKind, type ThreadListRow, } from "./thread";
+export { messageSchema, type Message } from "./message";
+export type { ErrorResponse, CreateThreadBody, LeagueRoomBody, TeamRoomBody, SendMessageBody, MarkReadBody, ThreadResponse, MessageResponse, MarkReadResponse, } from "./api";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACxD,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,OAAO,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Shared chat types and Zod schemas for QuickScores clients (RN, web).
+ * Kept in sync with Supabase migrations and docs/api-chat.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messageSchema = exports.threadListRowSchema = exports.threadSchema = exports.threadKindSchema = void 0;
+var thread_1 = require("./thread");
+Object.defineProperty(exports, "threadKindSchema", { enumerable: true, get: function () { return thread_1.threadKindSchema; } });
+Object.defineProperty(exports, "threadSchema", { enumerable: true, get: function () { return thread_1.threadSchema; } });
+Object.defineProperty(exports, "threadListRowSchema", { enumerable: true, get: function () { return thread_1.threadListRowSchema; } });
+var message_1 = require("./message");
+Object.defineProperty(exports, "messageSchema", { enumerable: true, get: function () { return message_1.messageSchema; } });

package/dist/types/message.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Message – matches chat_messages table.
+ */
+export declare const messageSchema: z.ZodObject<{
+    id: z.ZodString;
+    thread_id: z.ZodString;
+    sender_id: z.ZodNumber;
+    type: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    client_nonce: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type Message = z.infer<typeof messageSchema>;
+//# sourceMappingURL=message.d.ts.map

package/dist/types/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/types/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;iBASxB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/types/message.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messageSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Message – matches chat_messages table.
+ */
+exports.messageSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    thread_id: zod_1.z.string().uuid(),
+    sender_id: zod_1.z.number().int(),
+    type: zod_1.z.string(),
+    body: zod_1.z.string().nullable(),
+    payload: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    client_nonce: zod_1.z.string().nullable(),
+    created_at: zod_1.z.string(),
+});

package/dist/types/thread.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/**
+ * Thread kind – matches chat_threads.kind.
+ */
+export declare const threadKindSchema: z.ZodEnum<{
+    dm: "dm";
+    group: "group";
+    league: "league";
+    team: "team";
+}>;
+export type ThreadKind = z.infer<typeof threadKindSchema>;
+/**
+ * Thread – matches chat_threads table.
+ * No updated_at; schema only has created_at.
+ */
+export declare const threadSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        dm: "dm";
+        group: "group";
+        league: "league";
+        team: "team";
+    }>;
+    reuse_key: z.ZodNullable<z.ZodString>;
+    title: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    created_by: z.ZodNumber;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type Thread = z.infer<typeof threadSchema>;
+/**
+ * Thread list row – one row per thread from chat_thread_list view.
+ */
+export declare const threadListRowSchema: z.ZodObject<{
+    thread_id: z.ZodString;
+    kind: z.ZodEnum<{
+        dm: "dm";
+        group: "group";
+        league: "league";
+        team: "team";
+    }>;
+    title: z.ZodNullable<z.ZodString>;
+    reuse_key: z.ZodNullable<z.ZodString>;
+    created_by: z.ZodNumber;
+    created_at: z.ZodString;
+    user_id: z.ZodNumber;
+    last_read_message_id: z.ZodNullable<z.ZodString>;
+    last_message_at: z.ZodNullable<z.ZodString>;
+    last_message_preview: z.ZodNullable<z.ZodString>;
+    unread_count: z.ZodNumber;
+    other_participant_ids: z.ZodNullable<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type ThreadListRow = z.infer<typeof threadListRowSchema>;
+//# sourceMappingURL=thread.d.ts.map

package/dist/types/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/types/thread.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;EAA4C,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;iBAQvB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAa9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/types/thread.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.threadListRowSchema = exports.threadSchema = exports.threadKindSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Thread kind – matches chat_threads.kind.
+ */
+exports.threadKindSchema = zod_1.z.enum(["dm", "group", "league", "team"]);
+/**
+ * Thread – matches chat_threads table.
+ * No updated_at; schema only has created_at.
+ */
+exports.threadSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    kind: exports.threadKindSchema,
+    reuse_key: zod_1.z.string().nullable(),
+    title: zod_1.z.string().nullable(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    created_by: zod_1.z.number().int(),
+    created_at: zod_1.z.string(),
+});
+/**
+ * Thread list row – one row per thread from chat_thread_list view.
+ */
+exports.threadListRowSchema = zod_1.z.object({
+    thread_id: zod_1.z.string().uuid(),
+    kind: exports.threadKindSchema,
+    title: zod_1.z.string().nullable(),
+    reuse_key: zod_1.z.string().nullable(),
+    created_by: zod_1.z.number().int(),
+    created_at: zod_1.z.string(),
+    user_id: zod_1.z.number().int(),
+    last_read_message_id: zod_1.z.string().uuid().nullable(),
+    last_message_at: zod_1.z.string().nullable(),
+    last_message_preview: zod_1.z.string().nullable(),
+    unread_count: zod_1.z.number().int().min(0),
+    other_participant_ids: zod_1.z.array(zod_1.z.number().int()).nullable(),
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@quickscores/chat",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Shared chat types and Zod schemas for QuickScores (RN, web)",
+  "main": "./dist/types/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "db:start": "supabase start",
+    "db:stop": "supabase stop",
+    "db:reset": "supabase db reset",
+    "db:migrate": "supabase db push",
+    "db:diff": "supabase db diff -f",
+    "types:check": "tsc --noEmit",
+    "lint": "prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\" \"supabase/functions/**/*.ts\"",
+    "lint:fix": "prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\" \"supabase/functions/**/*.ts\"",
+    "test:api": "tsx scripts/test-chat-api.ts",
+    "test:league-team-rooms": "tsx scripts/test-league-team-rooms.ts"
+  },
+  "dependencies": {
+    "zod": "4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "dotenv": "^16.4.5",
+    "ky": "^1.8.0",
+    "prettier": "^3.8.0",
+    "supabase": "^2.75.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "github:quickscores/App2.0-Chat"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "default": "./dist/types/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "default": "./dist/types/index.js"
+    }
+  }
+}