docs(data-access): document services.postgrestClient (#1397)

## Summary
- Documents the `services.postgrestClient` API added in #1396 in both
README.md and CLAUDE.md
- Updates the "What You Get" and "TypeScript" sections in README.md
- Adds "Direct PostgREST Queries" section with usage examples to both
docs
- Adds `src/service/index.d.ts` to the Key Files table in CLAUDE.md

Follow-up to #1396 which was merged before docs were updated.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ekremney

packages/spacecat-shared-data-access/CLAUDE.md

@@ -21,7 +21,8 @@ Lambda/ECS service
 | File | Purpose |
 |------|---------|
 | `src/index.js` | Default export: `dataAccessWrapper(fn)` for Helix/Lambda handlers |
-| `src/service/index.js` | `createDataAccess(config, log?, client?)` factory |
+| `src/service/index.js` | `createDataAccess(config, log?, client?)` factory — returns entity collections + `services.postgrestClient` |
+| `src/service/index.d.ts` | `DataAccess` and `DataAccessServices` type definitions |
 | `src/models/base/schema.builder.js` | DSL for defining entity schemas (attributes, references, indexes) |
 | `src/models/base/base.model.js` | Base entity class (auto-generated getters/setters, save, remove) |
 | `src/models/base/base.collection.js` | Base collection class (findById, all, query, count) |
@@ -152,6 +153,22 @@ npm run test:it
 - PostgREST calls are stubbed via sinon
 - Each entity model and collection has its own test file
 
+## Direct PostgREST Queries
+
+`dataAccess.services.postgrestClient` exposes the raw `@supabase/postgrest-js` `PostgrestClient` for querying tables that don't have entity models (e.g. analytics views, reporting tables):
+
+```js
+const { postgrestClient } = context.dataAccess.services;
+
+const { data, error } = await postgrestClient
+  .from('brand_presence_executions')
+  .select('*')
+  .eq('site_id', siteId)
+  .limit(100);
+```
+
+This is the same client instance used internally by entity collections — same URL, auth, and schema.
+
 ## Common Patterns
 
 ### Collection query with WHERE clause

packages/spacecat-shared-data-access/README.md

@@ -16,9 +16,10 @@ npm install @adobe/spacecat-shared-data-access
 ## What You Get
 
 The package provides:
-- `createDataAccess(config, log?, client?)`
+- `createDataAccess(config, log?, client?)` — returns entity collections + `services.postgrestClient`
 - `dataAccessWrapper(fn)` (default export) for Helix/Lambda style handlers
 - Entity collections/models with stable external API shape for services
+- `services.postgrestClient` for direct PostgREST queries against non-entity tables
 
 ## Quick Start
 
@@ -89,6 +90,29 @@ The wrapper reads from `context.env`:
 - `S3_CONFIG_BUCKET`
 - `AWS_REGION`
 
+## Direct PostgREST Queries
+
+For querying PostgREST tables that are not modeled as entities (e.g. analytics views, reporting tables), the `postgrestClient` is available under `dataAccess.services`:
+
+```js
+const { Site } = dataAccess;                             // entity collections
+const { postgrestClient } = dataAccess.services;         // raw PostgREST client
+
+// Use entity collections as usual
+const site = await Site.findById(siteId);
+
+// Direct queries against non-entity tables
+const { data, error } = await postgrestClient
+  .from('brand_presence_executions')
+  .select('execution_date, visibility_score, sentiment')
+  .eq('site_id', siteId)
+  .gte('execution_date', '2025-01-01')
+  .order('execution_date', { ascending: false })
+  .limit(100);
+```
+
+This is the same `@supabase/postgrest-js` `PostgrestClient` instance used internally by the entity collections. Full IDE autocomplete is available for the query builder chain.
+
 ## Field Mapping Behavior
 
 Public model API remains camelCase while Postgres/PostgREST tables are snake_case.
@@ -383,7 +407,10 @@ export MYSTICAT_DATA_SERVICE_REPOSITORY=682033462621.dkr.ecr.us-east-1.amazonaws
 
 Type definitions are shipped from:
 - `src/index.d.ts`
-- `src/models/**/index.d.ts`
+- `src/service/index.d.ts` — `DataAccess` and `DataAccessServices` interfaces
+- `src/models/**/index.d.ts` — per-entity collection and model interfaces
+
+The `DataAccess` interface provides full typing for all entity collections and `services.postgrestClient` (typed as `PostgrestClient` from `@supabase/postgrest-js`).
 
 Use the package directly in TS projects; no extra setup required.