feat(data-access): expose postgrestClient for direct PostgREST queries (#1396)

## Summary
- Exposes the underlying `PostgrestClient` instance under a `services`
namespace on the object returned by `createDataAccess()`, enabling
direct PostgREST queries against tables that are not modeled as entities
(e.g. analytics views, brand presence tables)
- Adds full TypeScript typings for all 32 entity collections on the
`DataAccess` interface (previously typed as `object`)
- Re-exports 5 previously missing collection types from
`models/index.d.ts` (`ApiKey`, `AuditUrl`, `PageCitability`,
`PageIntent`, `Project`)

## Motivation

Some API endpoints need to query PostgREST tables that don't have
corresponding entity models in the data-access layer (e.g.
`brand_presence_executions`, `brand_metrics_weekly`). Previously,
developers resorted to reaching into collection internals like
`Site.postgrestService` to get the raw client. This change makes it a
first-class, typed API under a `services` namespace that cleanly
separates infrastructure from entity collections.

## Usage

```javascript
// Entity collections stay top-level
const { Site, Organization } = context.dataAccess;
const site = await Site.findById(siteId);

// Infrastructure services live under the services namespace
const { postgrestClient } = context.dataAccess.services;

// 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);
```

Full IDE autocomplete is available for the entire PostgREST query
builder chain (`.from()`, `.select()`, `.eq()`, `.gte()`, `.order()`,
`.range()`, `.rpc()`, etc.).

## Test plan
- [x] Existing unit tests updated to verify `services.postgrestClient`
is present and is the correct instance
- [x] All 1522 unit tests passing
- [x] Lint passing

🤖 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/src/index.d.ts

@@ -13,3 +13,4 @@
 export type * from './errors';
 export type * from './models';
 export type * from './util';
+export type { DataAccess } from './service';

packages/spacecat-shared-data-access/src/models/index.d.ts

@@ -10,31 +10,36 @@
  * governing permissions and limitations under the License.
  */
 
-export type * from './audit';
+export type * from './api-key';
 export type * from './async-job';
-export type * from './configuration';
+export type * from './audit';
+export type * from './audit-url';
 export type * from './base';
+export type * from './configuration';
 export type * from './consumer';
+export type * from './entitlement';
+export type * from './experiment';
 export type * from './fix-entity';
 export type * from './fix-entity-suggestion';
-export type * from './experiment';
-export type * from './entitlement';
 export type * from './import-job';
 export type * from './import-url';
 export type * from './key-event';
 export type * from './latest-audit';
 export type * from './opportunity';
 export type * from './organization';
+export type * from './page-citability';
+export type * from './page-intent';
+export type * from './project';
+export type * from './report';
 export type * from './scrape-job';
 export type * from './scrape-url';
+export type * from './sentiment-guideline';
+export type * from './sentiment-topic';
 export type * from './site';
 export type * from './site-candidate';
 export type * from './site-enrollment';
 export type * from './site-top-form';
 export type * from './site-top-page';
 export type * from './suggestion';
-export type * from './report';
 export type * from './trial-user';
-export type * from './trial-user-activity';
-export type * from './sentiment-guideline';
-export type * from './sentiment-topic';
+export type * from './trial-user-activity';

packages/spacecat-shared-data-access/src/service/index.d.ts

@@ -10,6 +10,41 @@
  * governing permissions and limitations under the License.
  */
 
+import type PostgrestClient from '@supabase/postgrest-js/dist/cjs/PostgrestClient';
+
+import type { ApiKeyCollection } from '../models/api-key';
+import type { AsyncJobCollection } from '../models/async-job';
+import type { AuditCollection } from '../models/audit';
+import type { AuditUrlCollection } from '../models/audit-url';
+import type { ConfigurationCollection } from '../models/configuration';
+import type { ConsumerCollection } from '../models/consumer';
+import type { EntitlementCollection } from '../models/entitlement';
+import type { ExperimentCollection } from '../models/experiment';
+import type { FixEntityCollection } from '../models/fix-entity';
+import type { FixEntitySuggestionCollection } from '../models/fix-entity-suggestion';
+import type { ImportJobCollection } from '../models/import-job';
+import type { ImportUrlCollection } from '../models/import-url';
+import type { KeyEventCollection } from '../models/key-event';
+import type { LatestAuditCollection } from '../models/latest-audit';
+import type { OpportunityCollection } from '../models/opportunity';
+import type { OrganizationCollection } from '../models/organization';
+import type { PageCitabilityCollection } from '../models/page-citability';
+import type { PageIntentCollection } from '../models/page-intent';
+import type { ProjectCollection } from '../models/project';
+import type { ReportCollection } from '../models/report';
+import type { ScrapeJobCollection } from '../models/scrape-job';
+import type { ScrapeUrlCollection } from '../models/scrape-url';
+import type { SentimentGuidelineCollection } from '../models/sentiment-guideline';
+import type { SentimentTopicCollection } from '../models/sentiment-topic';
+import type { SiteCollection } from '../models/site';
+import type { SiteCandidateCollection } from '../models/site-candidate';
+import type { SiteEnrollmentCollection } from '../models/site-enrollment';
+import type { SiteTopFormCollection } from '../models/site-top-form';
+import type { SiteTopPageCollection } from '../models/site-top-page';
+import type { SuggestionCollection } from '../models/suggestion';
+import type { TrialUserCollection } from '../models/trial-user';
+import type { TrialUserActivityCollection } from '../models/trial-user-activity';
+
 interface DataAccessConfig {
   postgrestUrl: string;
   postgrestSchema?: string;
@@ -19,8 +54,48 @@ interface DataAccessConfig {
   region?: string;
 }
 
+export interface DataAccessServices {
+  postgrestClient: PostgrestClient;
+}
+
+export interface DataAccess {
+  services: DataAccessServices;
+  ApiKey: ApiKeyCollection;
+  AsyncJob: AsyncJobCollection;
+  Audit: AuditCollection;
+  AuditUrl: AuditUrlCollection;
+  Configuration: ConfigurationCollection;
+  Consumer: ConsumerCollection;
+  Entitlement: EntitlementCollection;
+  Experiment: ExperimentCollection;
+  FixEntity: FixEntityCollection;
+  FixEntitySuggestion: FixEntitySuggestionCollection;
+  ImportJob: ImportJobCollection;
+  ImportUrl: ImportUrlCollection;
+  KeyEvent: KeyEventCollection;
+  LatestAudit: LatestAuditCollection;
+  Opportunity: OpportunityCollection;
+  Organization: OrganizationCollection;
+  PageCitability: PageCitabilityCollection;
+  PageIntent: PageIntentCollection;
+  Project: ProjectCollection;
+  Report: ReportCollection;
+  ScrapeJob: ScrapeJobCollection;
+  ScrapeUrl: ScrapeUrlCollection;
+  SentimentGuideline: SentimentGuidelineCollection;
+  SentimentTopic: SentimentTopicCollection;
+  Site: SiteCollection;
+  SiteCandidate: SiteCandidateCollection;
+  SiteEnrollment: SiteEnrollmentCollection;
+  SiteTopForm: SiteTopFormCollection;
+  SiteTopPage: SiteTopPageCollection;
+  Suggestion: SuggestionCollection;
+  TrialUser: TrialUserCollection;
+  TrialUserActivity: TrialUserActivityCollection;
+}
+
 export function createDataAccess(
   config: DataAccessConfig,
   logger: object,
   client?: object,
-): object;
+): DataAccess;

packages/spacecat-shared-data-access/src/service/index.js

@@ -98,5 +98,10 @@ export const createDataAccess = (config, log = console, client = undefined) => {
   const services = createServices(postgrestService, config);
   const entityRegistry = new EntityRegistry(services, config, log);
 
-  return entityRegistry.getCollections();
+  return {
+    ...entityRegistry.getCollections(),
+    services: {
+      postgrestClient: postgrestService,
+    },
+  };
 };

packages/spacecat-shared-data-access/test/unit/service/index.test.js

@@ -22,6 +22,8 @@ describe('service/index', () => {
     const dataAccess = createDataAccess({}, console, client);
 
     expect(dataAccess).to.be.an('object');
+    expect(dataAccess.services).to.be.an('object');
+    expect(dataAccess.services.postgrestClient).to.equal(client);
   });
 
   it('throws when postgrestUrl is missing and no client is provided', () => {
@@ -40,6 +42,9 @@ describe('service/index', () => {
     }, console);
 
     expect(dataAccess).to.be.an('object');
+    expect(dataAccess.services).to.be.an('object');
+    expect(dataAccess.services.postgrestClient).to.be.an('object');
+    expect(dataAccess.services.postgrestClient).to.have.property('from').that.is.a('function');
   });
 
   it('creates data access with optional S3 config', () => {