hermes-config/skills/software-development/pocketbase-development/SKILL.md

---
name: pocketbase-development
description: "PocketBase patterns: collection schemas, API quirks, sort-field traps, useToast provider, auth flow."
version: 1.2.0
metadata:
  hermes:
    tags: [pocketbase, backend, collections, debugging]
    related_skills: []
---

# PocketBase Development

## Overview

Common patterns, pitfalls, and fixes when building React apps backed by PocketBase. Covers collection creation, API query patterns, auth integration, SPQ legacy data model, and runtime debugging.

> **Reference:** `references/customer-db-integration.md` documents the SPQ Customer DB integration pattern: name splitting (firstName/middleName/lastName with backward-compat auto-compose), customer record auto-creation from quote/appointment/RO saves (`ensureCustomerRecord`), client-side duplicate detection, customerId pass-through across quotes → ROs → appointments, and multi-source data population (vehicles → quotes → ROs) when selecting a customer.
>
> **Reference:** `references/spq-legacy-data-model.md` documents the actual PocketBase schema for the ShopProQuote project — collection field names, vehicle data storage (no separate `vehicles` collection), the combine-and-deduplicate pattern across repairOrders/quotes, `customerName` vs `customerId` linkage (ALL existing ROs and quotes have empty `customerId`), quote services JSON display patterns (expandable rows with service line items), and migration patterns from legacy flat-text fields.
>
> **See also:** `pocketbase-react-apps/references/spq-pb-field-mapping.md` for the critical frontend-to-PB field name translation table (estimatedDuration → estimatedTime, customerType → financial JSON). Saves to wrong field names are silently dropped by PocketBase.
>
> **Reference:** `references/glitchtip-sentry-dsn-path-prefix.md` — Sentry SDK v10 DSN parser rejects multi-segment paths (`/glitchtip/1`). Fix: change DSN to bare project ID (`/1`) and add nginx regex location.
>
> **Reference:** `references/cross-origin-debugging.md` — Debugging the same React+PB app behaving differently on two domains (e.g., `shopproquote.graj-media.com` vs `grajmedia.duckdns.org`). Nginx config check → identical code → same backend → client-side localStorage stale state. Covers Zod validation failure tracing and the `spq-quote` localStorage key.
>
> **Reference:** `references/quote-to-ro-approved-services-sync.md` — Syncing approved quote services back to the originating repair order when saving a quote generated from an RO (`?fromRO=RO_ID`). Covers the merge logic (same-name update vs append), status preservation, and the two save paths (`handleSave` and `ensureShareToken`).

## Pitfalls

### Filter `~` (contains) operator can return 400 on some collections

PocketBase 0.39.1 may return `400 Bad Request` for the `~` (contains) filter operator on text fields in certain collections — even when the field and syntax are valid. The error message is the generic `"Something went wrong while processing your request."` with no field-level detail. This was observed on the `customers` collection's `name` and `phone` fields while the same SDK version handles `=` on `userId` without issue.

**Fix:** For collections with small record counts (single-shop data: customers, settings, etc.), skip server-side filters entirely and filter client-side:

```typescript
// ❌ Server-side filter — may return 400 for unknown reasons
const result = await pb.collection('customers').getList(1, 10, {
  filter: `name ~ '${query}'`,  // may 400 on some collections
  fields: 'id,name,phone',
});

// ✅ Client-side filter — fetch all + filter in JS
const result = await pb.collection('customers').getList(1, 500, {
  fields: 'id,name,phone',
  batch: 500,
});
const matched = (result.items as any[]).filter((c: any) =>
  (c.name || '').toLowerCase().includes(query.toLowerCase())
);
```

The `batch: 500` parameter fetches all records in a single request (PocketBase's default max batch is 500). For single-shop deployments this is always fast. Client-side filtering also avoids issues with escaping, case sensitivity, and operator support across PB versions.

**Key insight:** PocketBase's access rules (`userId = @request.auth.id`) are applied server-side automatically even without a `filter` parameter, so fetching all records and filtering client-side is a safe and reliable pattern for user-scoped data.

### sort `-created` fails with 400 on collections created via JS migrations

PocketBase v0.23+ does NOT auto-add system `created`/`updated` AutodateFields when a collection is created via `new Collection()` in a JS migration. Collections created through the admin UI DO get them. Using `sort: '-created'`, `sort: '-updated'`, or requesting `fields: '...,created,...'` in `getList()` queries on these collections returns a 400 error: "Something went wrong while processing your request."

**Workaround:** Use `sort: '-id'` instead. PocketBase IDs are time-sortable KSUIDs, so sorting by `-id` gives most-recent-first behavior.

**Proper fix (migration):** Add `AutodateField` instances to the affected collections:

```javascript
col.fields.add(new AutodateField({
  name: 'created',
  system: true,
  onCreate: true,
  onUpdate: false,
}));
col.fields.add(new AutodateField({
  name: 'updated',
  system: true,
  onCreate: true,
  onUpdate: true,
}));
app.save(col);
```

**Diagnosis steps when you see generic 400 errors on PB getList/getFullList:**

When PocketBase returns the generic `{"data":{},"message":"Something went wrong while processing your request.","status":400}`, the cause can be any query parameter (filter, sort, fields) referencing a non-existent field. Isolate the culprit systematically:

1. **Test without sort and fields first:**
   ```
   GET /api/collections/{name}/records?perPage=1
   ```
   If this works, the collection exists and is accessible.

2. **Add filter only:**
   ```
   GET /api/collections/{name}/records?filter=customerId='test'&perPage=1
   ```
   If this fails, the filter references a non-existent field.

3. **Add sort only:**
   ```
   GET /api/collections/{name}/records?sort=-created&perPage=1
   ```
   If this fails, the sort column doesn't exist on the collection.

4. **Add fields only:**
   ```
   GET /api/collections/{name}/records?fields=year,make,model&perPage=1
   ```
   If this fails, one of the requested fields doesn't exist.

5. **Check the actual SQLite schema:**
   ```bash
   # Host path — use docker inspect if unsure where the volume is
   sqlite3 /path/to/pb_data/data.db "PRAGMA table_info(collectionName);"
   # Or find the volume mount path via docker inspect (faster than find on large filesystems)
   docker inspect pocketbase | python3 -c "
   import json, sys
   data = json.load(sys.stdin)
   for mount in data[0].get('Mounts', []):
       if 'pb_data' in mount.get('Destination', ''):
           print(mount['Source'])
           break
   "
   ```
   Or check the `_collections` table's `fields` JSON:
   ```bash
   sqlite3 /path/to/pb_data/data.db "SELECT fields FROM _collections WHERE name='collectionName';" | python3 -c "import json, sys; [print(f['name']) for f in json.load(sys.stdin)]"
   ```
   Note: the `_collections` table has a `fields` column (not `schema`) that contains the full JSON array of field definitions.

6. **Verify with a `sort: '-id'` test** — PocketBase IDs are time-sortable KSUIDs, so `-id` sort is always available:
   ```
   GET /api/collections/{name}/records?sort=-id&perPage=1
   ```
   If this works but `sort=-created` doesn't, the collection is missing the system `created`/`updated` fields.

**Real-world affected collections (SPQ v2 project — all confirmed missing `created`/`updated` via PRAGMA table_info):**

| Collection | Created via | Missing fields? |
|---|---|---|
| `vehicles` | M16 JS migration (`new Collection()`) | Missing `created` and `updated` |
| `technicianInvites` | JS migration | Missing `created` and `updated` |
| `reminders` | JS migration (M26) | Missing `created` and `updated` |
| `quotes` | Admin UI | Has `createdAt`/`updatedAt` user fields but NO system `created`/`updated` |
| `repairOrders` | Admin UI | Has `createdAt`/`updatedAt` user fields but NO system `created`/`updated` |

All five were fixed in M28 by adding `AutodateField({ name: 'created', system: true, onCreate: true })` and `AutodateField({ name: 'updated', system: true, onCreate: true, onUpdate: true })`.

**Defensive fallback pattern when `created` is missing:** If the collection has a user-defined timestamp field like `createdAt`, sort by that instead:

```typescript
// ✅ Works even before M28 — createdAt is a user-defined text field
sort: '-createdAt'

// ❌ Fails on collections missing system created field
sort: '-created'
```

This pattern is used in `CustomerInfoPanel.tsx` for the quotes and repairOrders fallback queries. The `vehicles` query keeps `-created` because its try/catch wrapper handles failures gracefully while the migration is pending.

### Collection naming: camelCase not snake_case

PocketBase SDK auto-creates collections with camelCase names. A Firebase-based app may use snake_case (`repair_orders`) while the actual PB collection is `repairOrders`. Always verify collection names against the live PB instance before writing queries.

### useToast requires ToastProvider

The `useToast()` hook from `../components/ui/Toast` throws at runtime if `<ToastProvider>` is not wrapping the component tree. Always wrap `<BrowserRouter>` in `<ToastProvider>` in `App.tsx`:

```tsx
<BrowserRouter>
  <ToastProvider>
    <Routes>...</Routes>
  </ToastProvider>
</BrowserRouter>
```

### Vite build exit code 1 is often a false positive

Rolldown can emit non-fatal chunk-size warnings that cause exit code 1 even when the build succeeded. Check `dist/index.html` exists instead of trusting the exit code:
```bash
ls -la dist/index.html  # if it exists, build succeeded
```

### Creating collections without admin access

Non-admin PocketBase users cannot create collections via the REST API (returns 403). Collections must be created by an admin through the PocketBase dashboard at `http://host:8091/_/` or via admin-authenticated API calls.

### Filtering by userId on non-relational fields

When using `userId` as a plain text field (not a relation), the filter must use exact match:
```typescript
pb.collection('quotes').getList(1, 50, {
  filter: `userId = '${userId}'`,
  sort: '-id',
});
```

### Restrictive `fields` parameter can break queries

Using a `fields` parameter on `getList()` that lists fields not present on the collection will cause a 400 error (not just omit them). When in doubt, omit `fields` entirely and let PB return all fields:

```typescript
// ❌ Breaks if any field in the list doesn't exist
pb.collection('appointments').getList(1, 200, {
  fields: 'id,customerName,date,time,status,created,updated',
});

// ✅ Safe — returns whatever fields exist
pb.collection('appointments').getList(1, 200, {
  sort: '-id',
});
```

Same applies to `sort`: using `sort: 'date,time'` (two bare field names) may fail. Use the `+` or `-` prefix syntax: `sort: '-date,+time'` or just `sort: '-id'`.

### getFullList — load ALL records in one call (no pagination)

Use `getFullList()` to bypass the paged `getList()` pattern when you always want every matching record:

```typescript
// ❌ Paginated — requires "Load more" button + hasMore state
const records = await pb.collection('repairOrders').getList(page, perPage, {
  filter: `userId = '${userId}'`,
  sort: '-id',
});
// items in records.items, check records.totalPages for hasMore

// ✅ Un-paginated — returns ALL matching records in one array
const records = await pb.collection('repairOrders').getFullList({
  filter: `userId = '${userId}'`,
  sort: '-id',
});
// items returned directly as an array (no .items wrapper)
```

**When to use each:**

| Pattern | Use case | Return shape |
|---------|----------|-------------|
| `getList(page, perPage)` | Data you **want** paginated (big collections, server-side pages, "Load more" UX) | `{ items, page, perPage, totalItems, totalPages }` — items in `.items` |
| `getFullList({...})` | Small-to-medium collections you always want entirely in memory (typical single-shop data: ROs, customers, quotes) | Plain `T[]` — items returned directly from the SDK |

**Teardown the `usePagedList` hook when going un-paginated:**

If your app uses a `usePagedList<T>(fetchPage, perPage)` hook (like SPQ v2's `src/hooks/usePagedList.ts`), switching `fetchPage` from `getList` to `getFullList` means you can:

1. Change `fetchPage` to return a single-page result:
   ```typescript
   const fetchAll = useCallback(async () => {
     const records = await pb.collection('repairOrders').getFullList({ filter: `userId = '${userId}'` });
     return { items: records, page: 1, perPage: 999999, totalItems: records.length, totalPages: 1 };
   }, [userId]);
   ```
2. `hasMore` becomes always `false` (page 1 of 1 total pages)
3. The "Load more" button never renders
4. `refresh` re-fetches the full list — no accumulator state to manage

### JSON text fields: PocketBase may auto-parse or return raw strings

PocketBase stores JSON data as TEXT in the SQLite database. When the API returns these fields, **they may arrive as either a parsed JavaScript object/array OR as a raw JSON string**, depending on how the SDK serializes them. Always normalize:

```typescript
let items = raw;
if (typeof raw === 'string') {
  try { items = JSON.parse(raw); } catch { items = []; }
}
if (!Array.isArray(items)) items = [];
```

This applies to the `services` field on both `quotes` and `repairOrders` collections. A `parseQuoteServices` function that only handles strings will silently return empty for pre-parsed arrays.

### Row-level security blocks cross-user data access

All SPQ collections use the access rule:
```
listRule: userId = @request.auth.id
viewRule: userId = @request.auth.id
```

This means **a user can only see records where `userId` matches their own auth ID**. If `demo@shop.com` logs in, they see zero customers/quotes/ROs because the data belongs to `mani8994@gmail.com`. The query filter doesn't matter — PocketBase applies the access rule first.

**Implications:**
- You cannot query across users with a user-level auth token
- To work around this for admin-style views, you need an admin/superuser token that bypasses the rules
- Or modify the collection rules to allow broader access (e.g., remove the userId restriction, or add an OR condition)
- The legacy site worked because it was deployed in the same PocketBase instance with the data owner's credentials

**To verify access:** Always test API calls directly with the authenticated user's token before assuming data exists. A 404 `"not found"` or empty result set often means the userId rule is blocking access.

### Detecting missing collections gracefully

```typescript
try {
  const records = await pb.collection('name').getList(1, 1);
} catch (err) {
  const msg = err instanceof Error ? err.message : '';
  if (msg.includes('not found') || msg.includes('Missing collection')) {
    setCollectionMissing(true);  // show setup banner
  }
}
```

### PocketBase SDK `import` keyword breaks Vite/esbuild

The PocketBase JS SDK (v0.27.0) uses `import` as a method name in `CollectionService.import()`. Both Vite's esbuild pre-bundler and the browser's native parser treat `import(` as a dynamic import expression and throw `Uncaught SyntaxError: Unexpected token '('`.

**Fix:** Patch `node_modules/pocketbase/dist/pocketbase.es.mjs` to rename the method:

```bash
sed -i 's/async import(/async _import(/g' node_modules/pocketbase/dist/pocketbase.es.mjs
```

Then add to `vite.config.ts` to serve the raw ESM file (skip pre-bundling):

```typescript
export default defineConfig({
  optimizeDeps: {
    exclude: ['pocketbase'],
  },
  // ...
});
```

### Creating NEW collections via JS migrations (v0.39+)

The `new Collection({...})` constructor works in v0.39 JS migrations, but field-based API rules **cannot be set at all via JS migrations** — the rule validator runs against a schema snapshot that never catches up to include the new fields, even in a separate migration file with `findCollectionByNameOrId()`.

**✅ Working pattern — save with empty rules, skip field-based rules:**

```javascript
migrate(
  (app) => {
    var col = new Collection({
      name: 'myNewCollection',
      type: 'base',
      schema: [
        new TextField({ name: 'fieldName', required: true }),
        new JSONField({ name: 'jsonField', required: false }),
        new BoolField({ name: 'active', required: false }),
      ],
      listRule: '',      // empty string = unrestricted (no filter)
      viewRule: '',      // empty = unrestricted
      createRule: null,  // null = no public API creates
      updateRule: null,
      deleteRule: null,
    });
    app.save(col);
    console.log('[MX] created collection');
  },
  function(app) {
    var col = app.findCollectionByNameOrId('myNewCollection');
    if (col) { app.deleteCollection(col); }
  }
);
```

**❌ Do NOT attempt to set field-referencing rules** (`shopUserId = @request.auth.id`, `roId = @request.query.roId`) in any migration file — it fails with `listRule: Invalid rule. Raw error: invalid left operand "fieldName" - unknown field "fieldName"`. This affects:
- `app.save(col)` with rules set on the constructor object
- `app.save(col)` with `.listRule = '...'` on the same collection object after a prior save
- `app.save(col)` after `findCollectionByNameOrId()` in a completely separate migration file (M25+1)
- Every technique tested on PB 0.39.1 with `app.save()` on collections created via JS migration

**Workaround for single-shop deployments:** The collections are usable without field-based rules — the frontend API queries filter by userId/shopUserId client-side, and `createRule: null` / `updateRule: null` / `deleteRule: null` prevents public API writes on write-protected collections (like the audit log). Accept that the collection's list/view rules are unrestricted at the API level and scope in the frontend.

**⚠️ REST API workaround:** If field-based rules are genuinely required, create the collection AND set rules via the REST API (admin auth token), not JS migrations:

```python
# Step 1: POST the collection with rules directly (works via REST API!)
result = api("POST", "/api/collections", {
    "name": "myCollection",
    "type": "base",
    "listRule": "shopUserId = @request.auth.id",
    "fields": [
        {"name": "shopUserId", "type": "text", "required": True},
        {"name": "customerName", "type": "text"},
    ],
}, token=admin_token)
```

The REST API's schema validator works correctly because it validates against the full collection body before committing. Only the Goja JS migration runtime has this schema-snapshot limitation.

**Available field constructors (PB 0.39):**
- `new TextField({ name, required })` — text values, also used for ISO date strings
- `new JSONField({ name, required })` — JSON blobs (stored as TEXT in SQLite)
- `new BoolField({ name, required })` — boolean
- `new NumberField({ name, required })` — numeric
- `new EmailField({ name, required })` — email
- `new SelectField({ name, values, required })` — dropdown
- `new FileField({ name, maxSize, allowedMimeTypes })` — file upload

**`DateTimeField` does NOT exist** — use `new TextField({ name: 'at', required: true })` and store ISO 8601 strings.

**Field names must be unique within a collection's schema.** The `find()` check `!col.fields.find(f => f.name === 'existingField')` guards against duplicate field attempts during re-migration.

### Creating records in migration hooks (v0.39+)

```javascript
app.onRecordUpdateRequest(function(e) {
  if (e.collection.name !== 'sourceCollection') return;
  if (!e.oldRecord) return;

  var col = app.findCollectionByNameOrId('targetCollection');
  var data = {
    sourceId: e.record.id,
    value: e.record.get('someField'),
    at: new Date().toISOString(),
  };

  try {
    var rec = new Record(col, data);
    e.dao.saveRecord(rec);
  } catch (err) {
    console.error('[MX] save error: ' + String(err));
  }
});
```

The `new Record(col, data)` constructor accepts a collection object and a plain data object. The record is persisted via `e.dao.saveRecord(rec)` (not `app.save()` or `rec.save()`).

### Hook API names (v0.39+)

| Hook name | Fires | Use case |
|---|---|---|
| `app.onRecordCreateRequest(e)` | Before create | Modify/validate new records |
| `app.onRecordUpdateRequest(e)` | Before update | Check changes, send emails, write audit logs. **NOT** `onRecordBeforeUpdateRequest` or `onRecordAfterUpdateRequest` — those names don't exist. |
| `app.onRecordDeleteRequest(e)` | Before delete | Prevent deletion, cleanup references |

`onRecordUpdateRequest` has access to `e.oldRecord` for diffing changes. This is the only hook needed for both pre-update validation and post-update notification — since it fires before the DB write, throw an `ApiError(code, message)` to reject the update, or add side-effects (email, audit records) that are best-effort.

The `e.httpContext` object exists on update hooks for accessing request data:
```javascript
var shareToken = '';
try {
  shareToken = String(e.httpContext.request.query.get('shareToken') || '');
} catch (_) { return; }
```

### Throwing errors in hooks

```javascript
if (new Date() > expiryDate) {
  throw new ApiError(410, 'Quote expired');
}
```

`throw new ApiError(statusCode, message)` rejects the request with the given HTTP status code and message. Valid in `onRecordCreateRequest`, `onRecordUpdateRequest`, and `onRecordDeleteRequest`. The frontend receives the status code in `err.status`.

### Sending emails from hooks (PB 0.39 mailer)

PB 0.39 SMTP must be configured via env vars (`PB_SMTP_ENABLED`, `PB_SMTP_HOST`, etc.). The mailer API:

```javascript
try {
  app.getMailer().send({
    to: [{ address: 'user@example.com' }],
    subject: 'Quote Approved',
    html: '<h2>Quote approved</h2><p>Details...</p>',
  });
} catch (err) {
  console.error('[MX] email failed: ' + String(err));
}
```

The `to` field is an array of `{ address, name }` objects. `name` is optional. The mailer is fire-and-forget in hook context — if it fails, log and proceed.

### JS migration API: v0.22 vs v0.39+ incompatibility

PocketBase v0.23+ completely changed the embedded JS migration API. Old v0.22-style migration files silently skip on v0.39+.

**❌ OLD syntax (v0.22, does NOT work on v0.39+):**
```javascript
migrate((db) => {
    const col = db.findCollectionByNameOrId('users');
    const f = new CollectionField({
        name: 'role', type: 'select', values: ['advisor', 'technician', 'mobile']
    });
    col.fields.add(f);
    db.save(col);
});
```

**Error on v0.39+:** `ReferenceError: CollectionField is not defined`

**✅ REST API alternative (works on all versions >v0.23):**

When a JS migration file fails due to API incompatibility, use the REST API to PATCH the collection schema directly. This avoids writing Go-compatible JS migrations altogether.

```python
import subprocess, json

# 1. Auth as superuser
auth = subprocess.run([
    "curl", "-s", "-X", "POST",
    "http://127.0.0.1:8091/api/collections/_superusers/auth-with-password",
    "-H", "Content-Type: application/json",
    "-d", '{"identity":"admin@shop.com","password":"..."}'
], capture_output=True, text=True, timeout=10)
token = json.loads(auth.stdout)["token"]

# 2. GET current schema (must include ALL existing fields in PATCH payload)
get_req = subprocess.run([
    "curl", "-s", "http://127.0.0.1:8091/api/collections/users",
    "-H", f"Authorization: Bearer ***    ], capture_output=True, text=True, timeout=10)
collection = json.loads(get_req.stdout)
new_fields = list(collection["fields"])

# 3. Append new fields
new_fields.append({"name": "role", "type": "select", "values": ["advisor","technician","mobile"]})
new_fields.append({"name": "shopUserId", "type": "text"})
new_fields.append({"name": "displayName", "type": "text"})

# 4. PATCH with full fields array (replace entire field list)
subprocess.run([
    "curl", "-s", "-X", "PATCH", "http://127.0.0.1:8091/api/collections/users",
    "-H", f"Authorization: Bearer ***    "-H", "Content-Type: application/json",
    "-d", json.dumps({"fields": new_fields})
], capture_output=True, text=True, timeout=10)
```

**CRITICAL:** The PATCH payload must include ALL existing fields, not just the new ones — the `fields` array replaces the entire schema. Omitting existing fields drops them.

**Detection:** Run the migration explicitly to surface errors:
```bash
docker exec pocketbase /usr/local/bin/pocketbase --dir=/pb_data --migrationsDir=/pb_data/migrations migrate
```
If this passes cleanly, the migration will also apply on container restart. If it errors, use the REST API fallback above.

**Cleanup failed JS files after REST API workaround:** After applying the schema changes via REST API (PATCH fields or POST new collections), you MUST remove the failing JS migration file from `pb_data/migrations/`. PocketBase keeps trying it on every restart and logs a silent error each time — it won't crash but it's noise and may mask real problems.

```bash
rm /home/ray/docker/pocketbase/pb_data/migrations/1740000000001_*.js
# Then restart so the container starts clean
docker restart pocketbase
```

**REST API fallback also applies to creating NEW collections** — not just adding fields. The same two-step pattern works for full collection creation:

```python
# Step 1: POST the collection (with null rules to avoid constraint issues)
result = api("POST", "/api/collections", {
    "name": "technicianAssignments",
    "type": "base",
    "fields": [
        {"name": "shopUserId", "type": "text", "required": True},
        {"name": "status", "type": "select",
         "values": ["pending", "in_progress", "waiting_parts", "completed"]},
        # ... more fields
    ]
})
cid = result["id"]

# Step 2: PATCH the rules separately (cleaner separation of concerns)
result = api("PATCH", f"/api/collections/{cid}", {
    "listRule": "shopUserId = @request.auth.id || technicianUserId = @request.auth.id",
    "createRule": "shopUserId = @request.auth.id",
})
```

### PocketBase v0.39.x superuser auth

Superuser authentication is at the collections endpoint, NOT the legacy `/api/admins/` path:

```bash
# ✅ Correct (v0.39.x)
POST /api/collections/_superusers/auth-with-password
body: {"identity": "admin@example.com", "password": "..."}

# ❌ Wrong (legacy — returns 404)
POST /api/admins/auth-with-password
```

Create a superuser via CLI if none exists:
```bash
docker exec pocketbase /usr/local/bin/pocketbase superuser upsert admin@shop.com PASSWORD --dir /pb_data
```

### Creating collections via API (v0.39.x)

Use `fields` not `schema` in the payload. Match existing collection patterns — most SPQ collections use `text` for `userId` (not `relation`):

```python
api("POST", "/api/collections", {
    "name": "collection_name",
    "type": "base",
    "listRule": "userId = @request.auth.id",
    "viewRule": "userId = @request.auth.id",
    "createRule": "@request.auth.id != ''",
    "updateRule": "userId = @request.auth.id",
    "deleteRule": "userId = @request.auth.id",
    "fields": [
        {"name": "name", "type": "text", "required": True},
        {"name": "userId", "type": "text", "required": True},
    ],
}, token=admin_token)
```

The API returns 400 with specific field-level errors if the schema is wrong — inspect `resp["data"]["fields"]` for detail.

### Vite dev proxy for PocketBase needs explicit `rewrite`

When proxying `/pb` to PocketBase in Vite dev, add an explicit `rewrite` rule to strip the prefix:

```typescript
server: {
  proxy: {
    '/pb': {
      target: 'http://127.0.0.1:8091',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/pb/, ''),
    },
  },
}
```

Without `rewrite`, some PocketBase versions serve the admin UI HTML for proxied paths instead of the API JSON.

## PocketBase API Quick Reference

- Auth: `POST /api/collections/users/auth-with-password` with `{identity, password}`
- List: `GET /api/collections/{name}/records?page=1&perPage=50&filter=...&sort=-id`
- Create: `POST /api/collections/{name}/records`
- Update: `PATCH /api/collections/{name}/records/{id}`
- Delete: `DELETE /api/collections/{name}/records/{id}`
- Health: `GET /api/health`
- Admin dashboard: `http://host:8091/_/`

## SDK Patterns

```typescript
import PocketBase from 'pocketbase';
export const pb = new PocketBase('/pb');
pb.autoCancellation(false);

// Auth
const auth = await pb.collection('users').authWithPassword(email, password);
const userId = pb.authStore.model?.id;
pb.authStore.clear();  // logout

// CRUD
const result = await pb.collection('name').getList(page, perPage, { filter, sort });
const record = await pb.collection('name').create({ field: value });
await pb.collection('name').update(id, { field: newValue });
await pb.collection('name').delete(id);
```

## React Integration

```tsx
import { pb } from '../lib/pocketbase';
import { useToast } from '../components/ui/Toast';
// Must be wrapped in <ToastProvider>
```

### Settings merge: always use spread, never explicit field lists

When loading settings from a PocketBase JSON field into local state, use `{ ...DEFAULT_SETTINGS, ...data }` spread pattern. An explicit field-by-field merge silently drops any fields that exist in `DEFAULT_SETTINGS` but were not added to the merge logic — a recurring bug when new settings are added later.

```typescript
// ❌ Brittle — every new field must be manually added here
const merged: ShopSettings = {
  ...DEFAULT_SETTINGS,
  businessName: (d.businessName as string) || '',
  taxRate: Number(d.taxRate ?? 0),
  // ... 10+ more fields — easy to miss new ones
};

// ✅ Future-proof — spread includes all fields automatically
const merged: ShopSettings = { ...DEFAULT_SETTINGS, ...d } as ShopSettings;
```

This also means DEFAULT_SETTINGS must be the single source of truth for all fields and their defaults. When adding new settings fields, add them to DEFAULT_SETTINGS first, then the spread handles the rest.

### Nested component input focus loss

When an input inside a nested function component loses focus on every keystroke, the component is being recreated on every render. React treats a nested function as a new component type, destroying and recreating the DOM.

**Fix:** Extract the component to a file-level `memo`'d component so its identity is stable across renders. Never define components (functions that return JSX) inside other components — always at module scope.

```tsx
const ServiceRow = memo(function ServiceRow({ service, onUpdate, ... }: Props) {
  return <input value={service.price} onChange={...} />;
});
```

### JSON fields from PocketBase

PB `json` type fields may arrive as serialized JSON strings instead of parsed objects/arrays, depending on how the record was created. Always normalize:

```typescript
// Fetch time normalization (safe)
let services = item.services || [];
if (typeof services === 'string' && services.trim()) {
  try { services = JSON.parse(services); } catch { services = []; }
}
if (!Array.isArray(services)) services = [];
```

And when consuming a possibly-string field:
```typescript
function calcROTotals(services: ROService[]) {
  const arr = Array.isArray(services) ? services : [];
  const total = arr.reduce(...);
}
```

### Date formatting crashes (Invalid time value)

`new Date(undefined)` produces `Invalid Date`, and calling `.toLocaleDateString()` or `Intl.DateTimeFormat().format()` on it throws `RangeError: Invalid time value`. Always guard:

```typescript
function formatDate(iso: string | undefined | null) {
  if (!iso) return '—';
  const d = new Date(iso);
  if (isNaN(d.getTime())) return '—';
  return new Intl.DateTimeFormat('en-US', {...}).format(d);
}
```

### Tesseract.js in Vite

Dynamic CDN imports like `import('https://cdn.jsdelivr.net/...')` don't work in Vite production builds. Use a static npm import instead:

```typescript
// ✅ Correct — Vite bundles it
import Tesseract from 'tesseract.js';

// ❌ Wrong — fails in prod
const Tesseract = (await import('https://cdn.jsdelivr.net/...')).default;
```

### PB sign-up (user registration)

PocketBase user creation requires `passwordConfirm` at the top level of the create payload. Without it, the API returns 400:

```typescript
await pb.collection('users').create({
  email: email.trim(),
  password,
  passwordConfirm: confirmPassword,  // ← REQUIRED, not a real field
  name: name.trim() || '',
  emailVisibility: true,
});
```

Common failure causes:
- **Email already exists** → PB returns 400 `"Failed to create record."` with `data.email.code === 'validation_not_unique'`
- **Password < 8 chars** → PB returns `"Must be at least 8 character(s)."`
- **Missing passwordConfirm** → 400 with validation error

The SDK throws `ClientResponseError` (extends Error). `.message` gives "Failed to create record."; field details are in `.response.data`.

### Custom service / dynamic item add: always wire onClick

When a button that creates a dynamic item (e.g., "Add as custom service") has no `onClick` handler, it silently does nothing. Subagents frequently leave buttons with label text but no action. Always verify that every "Add X" button in generated code has a wired click handler that creates the item and updates state:

```tsx
// ❌ Silent — no action
<button>Add as custom service</button>

// ✅ Wired
<button onClick={() => {
  const newItem = { id: `custom-${Date.now()}`, name: query.trim(), price: 0 };
  addService(newItem);
}}>Add as custom service</button>
```

### Appointments page: avoid restrictive PB query params

The `fields` and `sort` parameters in `pb.collection().getList()` will 400-error if any referenced field doesn't exist on the collection. Prefer minimal params:

```typescript
// ❌ Breaks if fields or sort column doesn't exist
pb.collection('appointments').getList(1, 200, {
  filter: `userId = '${userId}'`,
  sort: 'date,time',                      // wrong syntax for PB
  fields: 'id,name,date,status,created',  // any missing = 400
});

// ✅ Safe
pb.collection('appointments').getList(1, 200, {
  filter: `userId = '${userId}'`,
  sort: '-id',
});
```

## Repair Order Domain Patterns

### Promised Completion Time (Due Date Display)

Auto repair management apps show a "promised completion time" on active repair orders. The display format adapts to how close the date is:

```typescript
function formatDueDate(promisedTime: string | undefined | null) {
  if (!promisedTime) return '—';
  const d = new Date(promisedTime);
  if (isNaN(d.getTime())) return '—';
  const now = new Date();
  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
  const tomorrow = new Date(today.getTime() + 86400000);
  const nextWeek = new Date(today.getTime() + 7 * 86400000);
  const dateOnly = new Date(d.getFullYear(), d.getMonth(), d.getDate());
  const timeStr = d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });

  if (dateOnly.getTime() === today.getTime()) return `Today ${timeStr}`;
  if (dateOnly.getTime() === tomorrow.getTime()) return `Tomorrow ${timeStr}`;
  if (dateOnly.getTime() < nextWeek.getTime()) {
    const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
    return `${days[d.getDay()]} ${timeStr}`;
  }
  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
  return `${months[d.getMonth()]} ${d.getDate()} ${timeStr}`;
}
```

Outputs: `"Today 3:00 PM"`, `"Tomorrow 10:30 AM"`, `"Wed 2:00 PM"`, `"Jun 27 1:00 PM"`, `"—"`.

Store as ISO datetime string in the PB collection (`promisedTime` field). Use `<input type="datetime-local">` in forms.

### Fetching Repair Orders by Customer (Two Patterns)

Repair orders link to customers in two ways, each used for different purposes:

**1. Forward-link by `customerId` (detail view)** — The RO has a `customerId` field referencing the customer record. Use this when viewing one customer's details:

> **⚠ SPQ data reality:** In the current SPQ database, ALL 55 repair orders and ALL 47 quotes have an **empty `customerId` field**. The only reliable link is by `customerName`. Use pattern #2 (`customerName` filter) for detail views in SPQ. If `customerId` is ever populated in the future this pattern will work, but for now it returns zero results.

```typescript
const result = await pb.collection('repairOrders').getList(1, 100, {
  filter: `customerId = '${customerId}'`,
  sort: '-createdAt',
  fields: 'id,roNumber,customerId,customerName,vehicleInfo,vin,mileage,status,workStatus,createdAt,completedTime,writeupTime,technician,notes,services',
});
```

**2. Backward-link by `customerName` (vehicle discovery)** — Used when the customer has no `customerId` on the RO (legacy data pattern). Search all ROs by customer name to discover associated vehicles:

```typescript
const nameFilter = customerNames
  .map((n) => `customerName ~ '${n.replace(/'/g, "\\'")}'`)
  .join(' || ');

const result = await pb.collection('repairOrders').getList(1, 500, {
  filter: nameFilter,
  fields: 'vehicleInfo,vin,customerName',
});
```

The first pattern is for the Customer Detail view (that customer's ROs). The second is for the Customer List view (discovering vehicles across all customers).

### RO Status Values and Display

The DB uses these `workStatus` values (stored in `status` or `workStatus` field):

| DB value | Display label | Badge color |
|---|---|---|
| `active` / `open` | Open | Blue |
| `in-progress` / `in_progress` | In Progress | Yellow/Amber |
| `waiter` / `waiting_parts` | Waiting Parts | Orange |
| `completed` | Completed | Green |
| `delivered` | Delivered | Green |
| `cancelled` | Cancelled | Red |

Status label/color helpers:

```typescript
function getRoStatusLabel(ro: RepairOrderRecord): string {
  const s = ro.workStatus || ro.status || '';
  switch (s) {
    case 'active': case 'open': return 'Open';
    case 'in-progress': case 'in_progress': return 'In Progress';
    case 'waiter': case 'waiting_parts': return 'Waiting Parts';
    case 'completed': return 'Completed';
    case 'delivered': return 'Delivered';
    case 'cancelled': return 'Cancelled';
    default: return s || 'Unknown';
  }
}

function getRoStatusColor(ro: RepairOrderRecord): string {
  const s = ro.workStatus || ro.status || '';
  switch (s) {
    case 'active': case 'open':
      return 'bg-blue-50 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400';
    case 'in-progress': case 'in_progress':
      return 'bg-yellow-50 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400';
    case 'waiter': case 'waiting_parts':
      return 'bg-orange-50 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400';
    case 'completed': case 'delivered':
      return 'bg-green-50 text-green-700 dark:bg-green-900/30 dark:text-green-400';
    case 'cancelled':
      return 'bg-red-50 text-red-700 dark:bg-red-900/30 dark:text-red-400';
    default:
      return 'bg-gray-50 text-gray-700 dark:bg-gray-900/30 dark:text-gray-400';
  }
}
```

### Status Transition Buttons (Reversible)

Repair orders need reversible status changes — once marked "Completed", the user must be able to "Reopen" back to "Active". Always show context-appropriate buttons:

```
Active      → In Progress, Waiting Parts, Complete
In Progress → Active, Waiting Parts, Complete
Waiting Pts → Active, In Progress, Complete
Completed   → Reopen (→Active), Mark Delivered
Delivered   → Reopen (→Active)
```

## Local Dev Server

For local development with PocketBase on a different port, use the SPA+PB proxy server in `references/spa-pb-proxy.py`. It serves the Vite build output and proxies `/pb/*` API calls to PocketBase, with CORS headers. Set `SPQ_DIST` and `PB_URL` env vars, or edit the defaults.