feat(connect): extract the connector wire contract into packages/connect-contract (#2179)

* feat(connect): extract the connector wire contract into packages/connect-contract The definitions in lib/connect/contract.ts (key prefix, headers, entitlements path, entitlement and sync-report shapes) move into a standalone MIT package, packages/connect-contract (published as @accounted/connect-contract), joined by the error envelope, the stable error codes, and Zod schemas for every Peppol connector operation (lookup, submit, status, evidence, register, unregister, inbound list and xml) with an operation table. Shape only: no behaviour, no provider code. In-repo callers import through the tsconfig and vitest alias; lib/connect/contract.ts re-exports so nothing else changes. The point of the package is that either side of the connection can be built outside this repository: a self-hosted ledger talking to Accounted Connect, or another connector service talking to the open ledger. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> * docs(decisions): record the Connect direction, the Peppol proxy shape, and the contract package Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> --------- Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-02 20:57:47 +02:00
parent 8c8996773f
commit fcfa1ba974
10 changed files with 555 additions and 34 deletions
@@ -1,7 +1,9 @@
 /**
 * The wire contract between a self-hosted Accounted instance and the hosted
- * connector service (app.gnubok.se/api/connect/*). Shared by both sides so
- * the instance sync and the hosted endpoint cannot drift apart.
+ * connector service (app.gnubok.se/api/connect/*). The definitions live in
+ * the MIT package packages/connect-contract (published as
+ * @accounted/connect-contract) so that either side can be implemented outside
+ * this repository; this module re-exports them for in-repo callers.
 *
 * Background: a self-hosted instance runs everything itself except the
 * services only Accounted can operate (bank sync via our PSD2/AISP
@@ -12,34 +14,12 @@
 * hosted proxy, never a licence check inside the instance.
 */

-export const CONNECTOR_KEY_PREFIX = 'gnubok_ck_'
-
-/** Header alternative to `Authorization: Bearer`, for proxied calls where Authorization carries an upstream token. */
-export const CONNECTOR_KEY_HEADER = 'x-connector-key'
-
-export const CONNECTOR_ENTITLEMENTS_PATH = '/api/connect/entitlements'
-
-/** Default hosted origin. app.gnubok.se stays the machine-facing host for API traffic. */
-export const DEFAULT_CONNECT_BASE_URL = 'https://app.gnubok.se'
-
-export type ConnectorKeyStatus = 'active' | 'suspended' | 'revoked'
-
-/** What the hosted service tells an instance about its key. */
-export interface ConnectorEntitlements {
-  status: ConnectorKeyStatus
-  /** Capability keys the subscription covers (subset of CONNECTOR_CAPABILITIES). */
-  scopes: string[]
-  /** End of the paid period, ISO; null for an open-ended (manually issued) key. */
-  current_period_end: string | null
-  org_number: string
-  /** The instance origin this key is pinned to; null until the first sync claims it. */
-  instance_url: string | null
-  server_time: string
-}
-
-/** What an instance reports on every sync (quantity billing input). */
-export interface ConnectorSyncReport {
-  active_company_count: number
-  instance_url?: string
-  app_version?: string
-}
+export {
+  CONNECTOR_KEY_PREFIX,
+  CONNECTOR_KEY_HEADER,
+  CONNECTOR_ENTITLEMENTS_PATH,
+  DEFAULT_CONNECT_BASE_URL,
+  type ConnectorKeyStatus,
+  type ConnectorEntitlements,
+  type ConnectorSyncReport,
+} from '@accounted/connect-contract'