@revenexx/app-sdk 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,6 +31,18 @@ export { L as BACKDATING_FIELD, N as BACKDATING_INVALID, T as BACKDATING_SETTING
31
31
  * app deciding an approval has to be able to tell the two apart. An app that
32
32
  * only attributes — a "last edited by" — can ignore it.
33
33
  *
34
+ * A third person arrives the same way (ADR-0132 §9): a SALES REP.
35
+ * The rep portal's server asserts `rep:<rep_code>`, the gateway resolves it
36
+ * through the `sales-reps` app's role provider, and injects
37
+ * `X-Revenexx-Caller: rep`, `X-Revenexx-Rep` (the rep code) and the
38
+ * permissions — never the contact headers. A rep is always ASSERTED, and
39
+ * reads as the `rep` plane.
40
+ *
41
+ * The record-history envelope (`X-Revenexx-Audit`) is not read here. It is
42
+ * Baseline's evidence, not the app's: the adapters forward it to the data
43
+ * plane unchanged (adapters/runtime.ts, adapters/remote.ts), and the gateway
44
+ * signs a rep into it the same way it signs a contact.
45
+ *
34
46
  * Every header read here is set ONLY by the gateway: it builds a fresh header
35
47
  * set per dispatch and strips any copy a caller sent. So `actor.trust` cannot
36
48
  * be talked up from outside, and an app never has to decide whether to believe
@@ -42,6 +54,9 @@ type ActorTrust = 'authenticated' | 'asserted' | 'none';
42
54
  * Which side of the platform the caller is on.
43
55
  *
44
56
  * - `contact` — one of the tenant's own people: a buyer, an approver.
57
+ * - `rep` — one of the merchant's sales reps, asserted by the rep portal and
58
+ * named by their rep code (ADR-0132). Not a buyer: a rep acting FOR a buyer
59
+ * does so through a buyer session, which is the `contact` plane.
45
60
  * - `operator` — a human the PLATFORM knows and the tenant's records do not.
46
61
  * Back office: Cockpit staff, support, a partner operating the tenant. There
47
62
  * is no contact to check a per-row rule against, and that absence is the
@@ -52,18 +67,23 @@ type ActorTrust = 'authenticated' | 'asserted' | 'none';
52
67
  * treating "no contact resolved" as "must be the platform", which is also what
53
68
  * an unknown customer looks like.
54
69
  */
55
- type ActorPlane = 'contact' | 'operator' | 'system';
70
+ type ActorPlane = 'rep' | 'contact' | 'operator' | 'system';
56
71
  /** The acting person, as far as the platform can state it. */
57
72
  interface Actor {
58
73
  /** The authenticated human's platform subject, or null when none was proven. */
59
74
  user: string | null;
60
75
  /** Their email claim, or null. Attribution — never a lookup key to trust on its own. */
61
76
  email: string | null;
62
- /** The `customers` contact the platform resolved them to, or null. */
77
+ /** The `customers` contact the platform resolved them to, or null. Always null for a rep. */
63
78
  contact: string | null;
64
- /** That contact's organization, or null. */
79
+ /** That contact's organization, or null. Always null for a rep. */
65
80
  organization: string | null;
66
- /** The permissions the tenant's role provider granted them. Empty when there is no contact. */
81
+ /**
82
+ * The sales rep's code when the gateway resolved a rep (`X-Revenexx-Caller:
83
+ * rep` with `X-Revenexx-Rep`), or null. Set only when both arrive.
84
+ */
85
+ rep: string | null;
86
+ /** The permissions the tenant's role provider granted them. Empty when there is no contact or rep. */
67
87
  permissions: string[];
68
88
  /** How well `contact` is known. `none` when nobody was established at all. */
69
89
  trust: ActorTrust;
@@ -88,6 +108,10 @@ declare const ACTOR_HEADERS: {
88
108
  readonly contact: "x-revenexx-contact";
89
109
  readonly organization: "x-revenexx-organization";
90
110
  readonly permissions: "x-revenexx-permissions";
111
+ /** `contact` or `rep` — the kind of person the gateway resolved. */
112
+ readonly caller: "x-revenexx-caller";
113
+ /** The rep's code, beside `caller: rep`, percent-encoded as UTF-8 (RFC 3986). */
114
+ readonly rep: "x-revenexx-rep";
91
115
  };
92
116
  /**
93
117
  * Read the acting person out of a request's headers.
@@ -196,8 +220,8 @@ interface RouteContext<D extends SettingsDefaults = SettingsDefaults> {
196
220
  *
197
221
  * `c.tenant` says whose data this is; this says whose hand is on it. Read
198
222
  * `c.actor.authenticated()` before enforcing a per-person rule, and
199
- * `c.actor.plane` to tell one of the tenant's contacts from a back-office
200
- * operator from a system caller. Never derive either from the context
223
+ * `c.actor.plane` to tell one of the tenant's contacts from one of the
224
+ * merchant's sales reps, a back-office operator or a system caller. Never derive either from the context
201
225
  * token's claims: those describe the calling SYSTEM.
202
226
  */
203
227
  actor: Actor;
@@ -31,6 +31,18 @@ export { L as BACKDATING_FIELD, N as BACKDATING_INVALID, T as BACKDATING_SETTING
31
31
  * app deciding an approval has to be able to tell the two apart. An app that
32
32
  * only attributes — a "last edited by" — can ignore it.
33
33
  *
34
+ * A third person arrives the same way (ADR-0132 §9): a SALES REP.
35
+ * The rep portal's server asserts `rep:<rep_code>`, the gateway resolves it
36
+ * through the `sales-reps` app's role provider, and injects
37
+ * `X-Revenexx-Caller: rep`, `X-Revenexx-Rep` (the rep code) and the
38
+ * permissions — never the contact headers. A rep is always ASSERTED, and
39
+ * reads as the `rep` plane.
40
+ *
41
+ * The record-history envelope (`X-Revenexx-Audit`) is not read here. It is
42
+ * Baseline's evidence, not the app's: the adapters forward it to the data
43
+ * plane unchanged (adapters/runtime.ts, adapters/remote.ts), and the gateway
44
+ * signs a rep into it the same way it signs a contact.
45
+ *
34
46
  * Every header read here is set ONLY by the gateway: it builds a fresh header
35
47
  * set per dispatch and strips any copy a caller sent. So `actor.trust` cannot
36
48
  * be talked up from outside, and an app never has to decide whether to believe
@@ -42,6 +54,9 @@ type ActorTrust = 'authenticated' | 'asserted' | 'none';
42
54
  * Which side of the platform the caller is on.
43
55
  *
44
56
  * - `contact` — one of the tenant's own people: a buyer, an approver.
57
+ * - `rep` — one of the merchant's sales reps, asserted by the rep portal and
58
+ * named by their rep code (ADR-0132). Not a buyer: a rep acting FOR a buyer
59
+ * does so through a buyer session, which is the `contact` plane.
45
60
  * - `operator` — a human the PLATFORM knows and the tenant's records do not.
46
61
  * Back office: Cockpit staff, support, a partner operating the tenant. There
47
62
  * is no contact to check a per-row rule against, and that absence is the
@@ -52,18 +67,23 @@ type ActorTrust = 'authenticated' | 'asserted' | 'none';
52
67
  * treating "no contact resolved" as "must be the platform", which is also what
53
68
  * an unknown customer looks like.
54
69
  */
55
- type ActorPlane = 'contact' | 'operator' | 'system';
70
+ type ActorPlane = 'rep' | 'contact' | 'operator' | 'system';
56
71
  /** The acting person, as far as the platform can state it. */
57
72
  interface Actor {
58
73
  /** The authenticated human's platform subject, or null when none was proven. */
59
74
  user: string | null;
60
75
  /** Their email claim, or null. Attribution — never a lookup key to trust on its own. */
61
76
  email: string | null;
62
- /** The `customers` contact the platform resolved them to, or null. */
77
+ /** The `customers` contact the platform resolved them to, or null. Always null for a rep. */
63
78
  contact: string | null;
64
- /** That contact's organization, or null. */
79
+ /** That contact's organization, or null. Always null for a rep. */
65
80
  organization: string | null;
66
- /** The permissions the tenant's role provider granted them. Empty when there is no contact. */
81
+ /**
82
+ * The sales rep's code when the gateway resolved a rep (`X-Revenexx-Caller:
83
+ * rep` with `X-Revenexx-Rep`), or null. Set only when both arrive.
84
+ */
85
+ rep: string | null;
86
+ /** The permissions the tenant's role provider granted them. Empty when there is no contact or rep. */
67
87
  permissions: string[];
68
88
  /** How well `contact` is known. `none` when nobody was established at all. */
69
89
  trust: ActorTrust;
@@ -88,6 +108,10 @@ declare const ACTOR_HEADERS: {
88
108
  readonly contact: "x-revenexx-contact";
89
109
  readonly organization: "x-revenexx-organization";
90
110
  readonly permissions: "x-revenexx-permissions";
111
+ /** `contact` or `rep` — the kind of person the gateway resolved. */
112
+ readonly caller: "x-revenexx-caller";
113
+ /** The rep's code, beside `caller: rep`, percent-encoded as UTF-8 (RFC 3986). */
114
+ readonly rep: "x-revenexx-rep";
91
115
  };
92
116
  /**
93
117
  * Read the acting person out of a request's headers.
@@ -196,8 +220,8 @@ interface RouteContext<D extends SettingsDefaults = SettingsDefaults> {
196
220
  *
197
221
  * `c.tenant` says whose data this is; this says whose hand is on it. Read
198
222
  * `c.actor.authenticated()` before enforcing a per-person rule, and
199
- * `c.actor.plane` to tell one of the tenant's contacts from a back-office
200
- * operator from a system caller. Never derive either from the context
223
+ * `c.actor.plane` to tell one of the tenant's contacts from one of the
224
+ * merchant's sales reps, a back-office operator or a system caller. Never derive either from the context
201
225
  * token's claims: those describe the calling SYSTEM.
202
226
  */
203
227
  actor: Actor;
@@ -28,7 +28,7 @@ import {
28
28
  requestedMoment,
29
29
  runAt,
30
30
  updateFields
31
- } from "../chunk-PXQA7E4F.js";
31
+ } from "../chunk-FMHCS3ZH.js";
32
32
 
33
33
  // src/instrument.ts
34
34
  var started = false;
@@ -83,26 +83,42 @@ var ACTOR_HEADERS = {
83
83
  trust: "x-revenexx-actor-trust",
84
84
  contact: "x-revenexx-contact",
85
85
  organization: "x-revenexx-organization",
86
- permissions: "x-revenexx-permissions"
86
+ permissions: "x-revenexx-permissions",
87
+ /** `contact` or `rep` — the kind of person the gateway resolved. */
88
+ caller: "x-revenexx-caller",
89
+ /** The rep's code, beside `caller: rep`, percent-encoded as UTF-8 (RFC 3986). */
90
+ rep: "x-revenexx-rep"
87
91
  };
88
92
  var nullIfEmpty = (v) => v.trim() === "" ? null : v.trim();
93
+ var decodeRep = (v) => {
94
+ if (v === null) return null;
95
+ try {
96
+ return nullIfEmpty(decodeURIComponent(v));
97
+ } catch {
98
+ return null;
99
+ }
100
+ };
89
101
  function actorFrom(header) {
90
102
  const read = (name) => {
91
103
  const v = header(name);
92
104
  return typeof v === "string" ? v : "";
93
105
  };
94
106
  const user = nullIfEmpty(read(ACTOR_HEADERS.user));
95
- const contact = nullIfEmpty(read(ACTOR_HEADERS.contact));
96
- const permissions = read(ACTOR_HEADERS.permissions).split(",").map((p) => p.trim()).filter(Boolean);
107
+ const isRepCall = read(ACTOR_HEADERS.caller).trim().toLowerCase() === "rep";
108
+ const rep = isRepCall ? decodeRep(nullIfEmpty(read(ACTOR_HEADERS.rep))) : null;
109
+ const contact = isRepCall ? null : nullIfEmpty(read(ACTOR_HEADERS.contact));
110
+ const organization = isRepCall ? null : nullIfEmpty(read(ACTOR_HEADERS.organization));
111
+ const permissions = isRepCall && rep === null ? [] : read(ACTOR_HEADERS.permissions).split(",").map((p) => p.trim()).filter(Boolean);
97
112
  const raw = read(ACTOR_HEADERS.trust).trim().toLowerCase();
98
- const trust = user === null && contact === null ? "none" : user !== null && raw === "authenticated" ? "authenticated" : "asserted";
99
- const plane = contact !== null ? "contact" : user !== null ? "operator" : "system";
113
+ const trust = user === null && contact === null && rep === null ? "none" : !isRepCall && user !== null && raw === "authenticated" ? "authenticated" : "asserted";
114
+ const plane = rep !== null ? "rep" : contact !== null ? "contact" : user !== null ? "operator" : "system";
100
115
  const held = new Set(permissions);
101
116
  return {
102
117
  user,
103
118
  email: nullIfEmpty(read(ACTOR_HEADERS.email)),
104
119
  contact,
105
- organization: nullIfEmpty(read(ACTOR_HEADERS.organization)),
120
+ organization,
121
+ rep,
106
122
  permissions,
107
123
  trust,
108
124
  plane,