backbone-integrations 0.6.1

Integration registry: connectors, integration accounts and an idempotent inbound event lane, with one OAuth flow (HMAC-bound state, PKCE)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# =============================================================================
# Domain: Integrations
# Entity: IntegrationEvent
# Description: One inbound event from an external provider (a Midtrans payment notification, a Tokopedia
# order webhook, a bank-feed line). Providers deliver webhooks AT-LEAST-ONCE, so it is DEDUPED on
# (connector, external_id) — a retried notification never re-maps. It is mapped to an internal action via a
# TargetPort (a settled payment → backbone-payment; an order → backbone-selling); some events are
# intentionally IGNORED (a "pending" payment notification needs no internal action). Posts NO GL.
# =============================================================================

models:
  - name: IntegrationEvent
    collection: integration_events
    description: "One inbound event from an external provider, deduped + mapped to an internal action"
    fields:
      id:
        type: uuid
        attributes: ["@id", "@default(uuid)"]
        description: "Unique event id"
      connector_id:
        type: uuid
        attributes: ["@required", "@foreign_key(IntegrationConnector.id)"]
        description: "The connector this event arrived on"
      event_type:
        type: string
        attributes: ["@required", "@length(max=80)"]
        description: "The provider event type (payment_settled | order_created | statement_line | …)"
      external_id:
        type: string
        attributes: ["@required", "@length(max=200)", "@exclude_from_foreign_key_check"]
        description: "The provider's raw event/notification id — audit only, NOT dedup (it varies per notification)"
      business_key:
        type: string
        attributes: ["@required", "@length(max=200)"]
        description: "The BUSINESS action identity (order/transaction ref + terminal state, e.g. 'SO-9:settled') — the real dedup key, stable across the multiple notifications a provider sends per order"
      status:
        type: IntegrationStatus
        attributes: ["@required", "@default(received)"]
        description: "received → mapped | ignored | failed"
      payload:
        type: string
        attributes: ["@required", "@length(max=20000)"]
        description: "The raw provider payload (JSON)"
      mapped_ref_type:
        type: string?
        attributes: ["@length(max=60)"]
        description: "The internal record type this mapped to (payment | sales_order | bank_transaction)"
      mapped_ref_id:
        type: uuid?
        attributes: ["@exclude_from_foreign_key_check"]
        description: "The internal record # logical FK keyed by mapped_ref_type"
      error_detail:
        type: string?
        attributes: ["@length(max=1000)"]
        description: "Why mapping failed / the ignore reason"
      metadata:
        type: Metadata
        attributes: ["@audit_metadata"]
        description: "Audit metadata"
    indexes:
      # Dedup on the BUSINESS action identity, not the raw notification id — a provider sends multiple
      # notifications per order (pending → settled), each with a different notification id but the same
      # business action; keying on the notification id would apply the payment TWICE (maturity council
      # 2026-07-11).
      - type: unique
        fields: [connector_id, business_key]
      # No tenancy indexes (ADR-0029): the module is tenant-agnostic; the
      # composing service's tenancy decorator owns org scoping for this table.

enums:
  - name: IntegrationStatus
    description: "Event processing lifecycle"
    variants:
      - name: received
        description: "Recorded, not yet mapped"
        default: true
      - name: mapped
        description: "Mapped to an internal action"
      - name: ignored
        description: "Intentionally not mapped (no internal action needed)"
      - name: failed
        description: "Mapping failed"