@t4dt/t4data-cloud-message-client

Typed Client/Domain-Package für t4data.cloud (Messages + Partner API).

• Node: >= 18
• Build: TypeScript (liefert dist/ mit JS + Types)
• API-Stil: strikt typisiert, keine losen any-Typen

Installation

npm i @t4dt/t4data-cloud-message-client

Quickstart

Dieses Package ist in drei Ebenen strukturiert:

• HTTP: T4dataHttpClient + FetchT4dataHttpClient (Transport)
• Repository: z. B. PartnerRepository (reiner API-Zugriff)
• Service: z. B. MessageService, PartnerService (Domain-Validierung + Parsing)

HTTP-Client (Fetch)

import { FetchT4dataHttpClient } from '@t4dt/t4data-cloud-message-client';

const http = new FetchT4dataHttpClient({
  baseUrl: 'https://<deine-instanz>.t4data.cloud',
  apiKey: process.env.T4DATA_API_KEY ?? '',
  // optional, z.B. OAuth access token
  accessToken: process.env.T4DATA_ACCESS_TOKEN,
});

Wichtig: Für t4data.cloud/Supabase ist der Header apikey Pflicht (auch wenn du OAuth/Bearer nutzt).

Messages API

Die Typen und Aufrufe entsprechen der Edge Function supabase/functions/message (Zod MessageSchema, GetMessagesRequestSchema, Routen /message, /message/:id, /message/:id/exported).

Nachricht anlegen — es muss genau eines von data (JSON-Objekt) oder data_object_id (Storage-UUID) gesetzt sein (niemals beides). Optionale Felder wie auf dem Server: sender_id, custom_message_id. Die Nil-UUID für sender_id wird wie „nicht gesetzt“ behandelt.

Doku / Worker (post_message_service) nutzt andere Namen (sender, receiver, message_type_name). Dieses Paket spricht die Edge-Function per HTTP an, nicht den Service-Role-RPC. Zum Übernehmen der Doku-Felder ohne supabase-js:

import {
  MessageService,
  adaptPostMessageServiceLikeToCreatePayload,
} from '@t4dt/t4data-cloud-message-client';

const payload = adaptPostMessageServiceLikeToCreatePayload({
  sender: '<partner-uuid>',
  receiver: '<partner-uuid>',
  message_type_name: 'ORDER',
  data: { foo: 'bar' },
  custom_message_id: null,
  data_object_id: null,
});
await messageService.createGenericMessage(payload);

import { MessageService } from '@t4dt/t4data-cloud-message-client';

const messageService = new MessageService(http);

const created = await messageService.createGenericMessage({
  message_type: 'order.created',
  receiver_id: '00000000-0000-4000-8000-000000000000',
  data: { orderId: '123', source: 'erp' },
  // optional, z. B. Plattform-Admin / abweichender Absender — Feldname wie API: sender_id
  // sender_id: '00000000-0000-4000-8000-000000000001',
  // custom_message_id: 'ext-123',
});

// Alternative: große Nachricht nur per Storage-Referenz
// await messageService.createGenericMessage({
//   message_type: 'large.payload',
//   receiver_id: '00000000-0000-4000-8000-000000000000',
//   data_object_id: '00000000-0000-4000-8000-000000000002',
// });

const message = await messageService.getMessageById(created.id);

await messageService.markMessageExported(message.id); // API: 204 No Content

const list = await messageService.listMessages({
  include_exported: false,
  typeFilter: 'order.', // Query `type`, kommagetrennte Typnamen möglich
  created_after: undefined,
  created_before: undefined,
  limit: 1000,
  include_large_messages: false, // optional, Standard false
  // sender_id und custom_message_id: optional; custom_message_id erfordert sender_id
});

Partner API (Repository + Service)

import { PartnerRepository, PartnerService } from '@t4dt/t4data-cloud-message-client';

const repo = new PartnerRepository(http);
const partnerService = new PartnerService(repo);

const partners = await partnerService.listPartnersWithGlns();

Fehlerbehandlung

Alle Domain-/API-Fehler werden als ApiError geworfen.

import { ApiError } from '@t4dt/t4data-cloud-message-client';

try {
  // ... API Calls
} catch (e) {
  if (e instanceof ApiError) {
    // e.kind: 'DataError' | 'ConnectionError' | 'UnknownError'
    // e.statusCode?: number
    // e.details?: unknown (Original-Body)
    console.error(e.kind, e.statusCode, e.message);
  }
  throw e;
}

Semantik (vereinfacht):

• DataError: 4xx oder API liefert ein Error-Envelope ({ status: 'error', ... })
• ConnectionError: 5xx
• UnknownError: sonstige Fälle

Public API (Exports)

Das Package exportiert unter anderem:

• Errors: ApiError
• HTTP: T4dataHttpClient, FetchT4dataHttpClient
• Utilities: joinInstanceAndPath, JSON/UUID Typeguards
• Messages: MessageService, Message.types (Payloads/Records), adaptPostMessageServiceLikeToCreatePayload, PostMessageServiceLikePayload (Doku-Namen → HTTP-Payload)
• Partner: PartnerRepository, PartnerService, Partner.types

Siehe Entry-Point src/index.ts für die vollständige Export-Liste.

Entwicklung

npm run build
npm run dev
npm run lint

Lizenz

MIT