hazo_notes 1.1.6 → 2.0.0

package/README.md

@@ -70,21 +70,24 @@ Create `app/api/hazo_notes/[ref_id]/route.ts`:
 ```typescript
 import { createNotesHandler } from 'hazo_notes/api';
 import { getHazoConnectSingleton } from 'hazo_connect/nextjs/setup';
-// Import your auth and user lookup functions
-import { getSession } from '@/lib/auth'; // Replace with your auth
+import { hazo_get_tenant_auth } from 'hazo_auth/server-lib';
 import { getUserById } from '@/lib/users'; // Replace with your user lookup
+import type { NextRequest } from 'next/server';
 
 export const dynamic = 'force-dynamic';
 
 const { GET, POST } = createNotesHandler({
   getHazoConnect: () => getHazoConnectSingleton(),
-  getUserIdFromRequest: async (req) => {
-    // IMPORTANT: Replace with your authentication logic
-    const session = await getSession(req);
-    return session?.user?.id || null;
+  // Preferred: hazo_auth@6.x tenant auth. Used by both GET and POST.
+  getAuth: async (req) => {
+    const auth = await hazo_get_tenant_auth(req as NextRequest);
+    if (!auth.authenticated || !auth.user?.id) return null;
+    return {
+      user_id: auth.user.id,
+      scope_id: auth.selected_scope_id ?? null,
+    };
   },
   getUserProfile: async (userId) => {
-    // IMPORTANT: Replace with your user profile lookup
     const user = await getUserById(userId);
     return {
       id: userId,
@@ -98,6 +101,15 @@ const { GET, POST } = createNotesHandler({
 export { GET, POST };
 ```
 
+> **GET requires auth.** Starting in `1.2.0`, GET responds `401` when the auth
+> resolver returns `null`, matching POST. Older releases left GET anonymous.
+> If you're still on `hazo_auth@5.x`, use `getUserIdFromRequest` instead of
+> `getAuth` — the package falls back to it for backward compatibility.
+
+> **Error detail.** On `500` responses the underlying error message is
+> included as `cause` in dev (when `NODE_ENV !== 'production'`). Set
+> `expose_error_cause: false` to suppress, or `true` to force it on in prod.
+
 ### 3. Set Up Database
 
 Run the migration:
@@ -114,6 +126,11 @@ CREATE TABLE hazo_notes (
 );
 
 CREATE INDEX idx_hazo_notes_ref_id ON hazo_notes(ref_id);
+
+-- REQUIRED for PostgREST consumers — without this, GET/POST return 500 with
+-- cause "permission denied for table hazo_notes" (PostgREST error 42501).
+-- Shipped as migrations/002_grant_api_user_hazo_notes.sql.
+GRANT SELECT, INSERT, UPDATE, DELETE ON hazo_notes TO api_user;
 ```
 
 **SQLite:**
@@ -672,17 +689,43 @@ getUserProfile: async (userId) => {
 
 ### Authentication errors
 
-**Problem**: "Unauthorized" when adding notes.
+**Problem**: `401 Unauthorized` on GET or POST.
+
+**Solution**: Wire `getAuth` (preferred, hazo_auth@6.x) or `getUserIdFromRequest`
+(hazo_auth@5.x). GET and POST both require a non-null user; both return `401`
+if the resolver returns `null`.
 
-**Solution**: Implement `getUserIdFromRequest` to return authenticated user ID:
 ```typescript
+// hazo_auth@6.x — preferred
+getAuth: async (req) => {
+  const auth = await hazo_get_tenant_auth(req as NextRequest);
+  if (!auth.authenticated || !auth.user?.id) return null;
+  return { user_id: auth.user.id, scope_id: auth.selected_scope_id ?? null };
+}
+
+// hazo_auth@5.x — backward-compatible fallback
 getUserIdFromRequest: async (req) => {
   const session = await getSession(req);
-  if (!session?.user?.id) return null;
-  return session.user.id;
+  return session?.user?.id ?? null;
 }
 ```
 
+### PostgREST `permission denied for table hazo_notes` (500 with cause 42501)
+
+**Problem**: GET/POST return 500. Response includes
+`"cause": "permission denied for table hazo_notes"` (when `expose_error_cause`
+is enabled).
+
+**Solution**: Apply `migrations/002_grant_api_user_hazo_notes.sql`. It grants
+`SELECT, INSERT, UPDATE, DELETE` on `hazo_notes` to the `api_user` role used
+by PostgREST. Reproducing the underlying error directly:
+
+```bash
+curl "$POSTGREST_URL/hazo_notes?limit=1"
+# Before grant: 401 / "permission denied for table hazo_notes"
+# After grant:  [] or rows
+```
+
 ## Examples
 
 See the `test-app/` directory for complete working examples:

package/SETUP_CHECKLIST.md

@@ -66,15 +66,25 @@ CREATE TABLE IF NOT EXISTS hazo_notes (
 CREATE INDEX IF NOT EXISTS idx_hazo_notes_ref_id ON hazo_notes(ref_id);
 ```
 
-**Alternative**: Use the provided migration file:
+**Alternative**: Use the provided migration files:
 ```bash
-# PostgreSQL
+# PostgreSQL — apply both files in order
 psql -d your_database -f node_modules/hazo_notes/migrations/001_create_hazo_notes_table.sql
+psql -d your_database -f node_modules/hazo_notes/migrations/002_grant_api_user_hazo_notes.sql
 
-# SQLite
+# SQLite — only 001 (SQLite has no role system, skip 002)
 sqlite3 your_database.db < node_modules/hazo_notes/migrations/001_create_hazo_notes_table.sql
 ```
 
+> **PostgREST consumers MUST apply migration 002.** Without it, PostgREST
+> returns `42501 / permission denied for table hazo_notes` and the API
+> surfaces a generic 500. Migration 002 grants
+> `SELECT, INSERT, UPDATE, DELETE` on `hazo_notes` to `api_user`. Verify with:
+>
+> ```bash
+> curl "$POSTGREST_URL/hazo_notes?limit=1"   # should return [] not 401
+> ```
+
 ## API Routes
 
 ### 4. Create the notes API route
@@ -84,25 +94,27 @@ Create `app/api/hazo_notes/[ref_id]/route.ts`:
 ```typescript
 import { createNotesHandler } from 'hazo_notes/api';
 import { getHazoConnectSingleton } from 'hazo_connect/nextjs/setup';
-// Import your authentication and user lookup functions
-import { getSession } from '@/lib/auth';
+import { hazo_get_tenant_auth } from 'hazo_auth/server-lib';
 import { getUserById } from '@/lib/users';
+import type { NextRequest } from 'next/server';
 
 export const dynamic = 'force-dynamic';
 
 const { GET, POST } = createNotesHandler({
   getHazoConnect: () => getHazoConnectSingleton(),
 
-  getUserIdFromRequest: async (req) => {
-    // IMPORTANT: Replace this with your actual authentication logic
-    // This function should return the authenticated user's ID or null
-    const session = await getSession(req);
-    return session?.user?.id || null;
+  // Preferred (hazo_auth@6.x). Used by BOTH GET and POST — both require auth.
+  getAuth: async (req) => {
+    const auth = await hazo_get_tenant_auth(req as NextRequest);
+    if (!auth.authenticated || !auth.user?.id) return null;
+    return {
+      user_id: auth.user.id,
+      scope_id: auth.selected_scope_id ?? null,
+    };
   },
 
   getUserProfile: async (userId) => {
     // IMPORTANT: Replace this with your actual user profile lookup
-    // This function fetches user details for attribution
     const user = await getUserById(userId);
     return {
       id: userId,
@@ -117,9 +129,13 @@ export { GET, POST };
 ```
 
 **Important Notes**:
-- The `getUserIdFromRequest` function MUST return a valid user ID for POST requests
+- Either `getAuth` (hazo_auth@6.x) or `getUserIdFromRequest` (hazo_auth@5.x)
+  MUST be provided. GET and POST both return `401` if the resolver returns
+  `null`. GET-anonymous behavior from `1.1.x` is gone in `1.2.0`.
 - The `getUserProfile` function enriches notes with user information
 - If you don't have user profiles, you can omit `getUserProfile`
+- On a 500 response, the underlying error message is included as `cause`
+  in non-production. Set `expose_error_cause: false` to suppress.
 
 ### 5. (Optional) Create the files API route for file attachments
 

package/config/hazo_notes_config.ini

@@ -0,0 +1,48 @@
+# hazo_notes Configuration
+# This file configures the notes system behavior and storage
+#
+# Env-var overrides follow the pattern HAZO_NOTES_<SECTION>_<KEY> (uppercase).
+# Per-env overlays: place hazo_notes_config.<HAZO_ENV>.ini next to this file.
+
+[general]
+# Optional override for the deployment environment. Defaults to
+# HAZO_ENV → NODE_ENV → 'development' (resolved by hazo_core).
+# env = production
+
+[log.overrides]
+# Per-namespace log level overrides (per D-015). Format:
+#   <namespace> = <level>
+# Examples:
+# hazo_notes/poll = warn
+# hazo_notes      = debug
+
+[ui]
+# Background color for notes panel (Tailwind CSS class)
+background_color = bg-yellow-100
+
+# Panel presentation style: popover | slide_panel
+panel_style = popover
+
+# Save behavior: explicit (save/cancel buttons) | auto (save on blur)
+save_mode = explicit
+
+[storage]
+# File storage mode: jsonb (in database) | filesystem (on server)
+file_storage_mode = jsonb
+
+# Path for filesystem storage (only used when file_storage_mode = filesystem)
+file_storage_path = /uploads/notes
+
+[files]
+# Maximum file size in MB
+max_file_size_mb = 10
+
+# Allowed file types (comma-separated extensions)
+allowed_file_types = pdf,png,jpg,jpeg,gif,doc,docx
+
+# Maximum files per single note entry
+max_files_per_note = 5
+
+[logging]
+# Log file path
+logfile = logs/hazo_notes.log

package/db_setup_postgres.sql

@@ -0,0 +1,49 @@
+-- hazo_notes database schema
+-- PostgreSQL -- idempotent (safe to run multiple times)
+-- Run this file to set up all tables required by hazo_notes
+--
+-- Tables: hazo_notes
+
+-- ============================================================
+-- hazo_notes
+-- Database-backed notes linked to any entity via ref_id.
+-- Notes are stored as a JSONB array with user attribution and
+-- optional file attachments.
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS hazo_notes (
+  id           UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+  ref_id       UUID         NOT NULL,
+  note         JSONB        NOT NULL DEFAULT '[]'::jsonb,
+  created_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+  changed_at   TIMESTAMPTZ  NULL,
+  note_count   INTEGER      NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_notes_ref_id ON hazo_notes(ref_id);
+
+COMMENT ON TABLE  hazo_notes IS              'Notes linked to any entity via ref_id. note column is a JSONB array of {userid, created_at, note_text, note_files}.';
+COMMENT ON COLUMN hazo_notes.id IS           'Primary key UUID';
+COMMENT ON COLUMN hazo_notes.ref_id IS       'UUID reference to the parent entity (e.g. form field, document, task)';
+COMMENT ON COLUMN hazo_notes.note IS         'JSONB array of note entries';
+COMMENT ON COLUMN hazo_notes.created_at IS   'Timestamp when the notes row was first created';
+COMMENT ON COLUMN hazo_notes.changed_at IS   'Timestamp of the last modification to the notes';
+COMMENT ON COLUMN hazo_notes.note_count IS   'Denormalised count of notes, kept in sync on write to avoid parsing JSONB on read';
+
+-- ============================================================
+-- PostgREST role grants
+-- Required for the bundled API handlers, which talk to PostgREST.
+-- The api_user role must exist beforehand (created by hazo_connect setup).
+-- ============================================================
+
+DO $$ BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'api_user') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON hazo_notes TO api_user;
+  END IF;
+END $$;
+
+-- ============================================================
+-- Notify PostgREST to reload the schema cache
+-- ============================================================
+
+SELECT pg_notify('pgrst', 'reload schema');

package/db_setup_sqlite.sql

@@ -0,0 +1,22 @@
+-- hazo_notes database schema
+-- SQLite -- idempotent (safe to run multiple times)
+-- Run this file to set up all tables required by hazo_notes
+--
+-- Tables: hazo_notes
+
+-- ============================================================
+-- hazo_notes
+-- Notes linked to any entity via ref_id. The note column is a
+-- JSON-encoded array stored as TEXT (SQLite has no native JSONB).
+-- ============================================================
+
+CREATE TABLE IF NOT EXISTS hazo_notes (
+  id           TEXT     PRIMARY KEY,
+  ref_id       TEXT     NOT NULL,
+  note         TEXT     NOT NULL DEFAULT '[]',
+  created_at   TEXT     NOT NULL DEFAULT (datetime('now')),
+  changed_at   TEXT,
+  note_count   INTEGER  NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_notes_ref_id ON hazo_notes(ref_id);

package/dist/api/create_files_handler.d.ts

@@ -32,7 +32,7 @@ import type { CreateFilesHandlerOptions, FileUploadApiResponse } from '../types/
  * @returns Object with POST (upload) and GET (download) handlers
  */
 export declare function createFilesHandler(options: CreateFilesHandlerOptions): {
-    GET: (request: Request, context: {
+    GET: (request: Request, _context: {
         params: Promise<{
             file_id?: string;
         }>;

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

@@ -1 +1 @@
-{"version":3,"file":"create_files_handler.d.ts","sourceRoot":"","sources":["../../src/api/create_files_handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EACV,yBAAyB,EAEzB,qBAAqB,EAEtB,MAAM,mBAAmB,CAAC;AAkC3B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB;mBAyIxD,OAAO,WACP;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,KACjD,OAAO,CAAC,YAAY,CAAC;oBArHK,OAAO,KAAG,OAAO,CAAC,YAAY,CAAC,qBAAqB,CAAC,CAAC;EAuLpF"}
+{"version":3,"file":"create_files_handler.d.ts","sourceRoot":"","sources":["../../src/api/create_files_handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,OAAO,KAAK,EACV,yBAAyB,EAEzB,qBAAqB,EAEtB,MAAM,mBAAmB,CAAC;AAqC3B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB;mBAgKxD,OAAO,YACN;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,KAClD,OAAO,CAAC,YAAY,CAAC;oBA5IK,OAAO,KAAG,OAAO,CAAC,YAAY,CAAC,qBAAqB,CAAC,CAAC;EA0OpF"}