@intellectual-frontiers/integrations 0.0.0-stage → 0.1.1

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.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +8 -2
  3. package/dist/governance/exchange.d.ts +224 -0
  4. package/dist/governance/exchange.js +86 -0
  5. package/dist/governance/ids.d.ts +61 -0
  6. package/dist/governance/ids.js +53 -0
  7. package/dist/governance/mod.d.ts +11 -0
  8. package/dist/governance/mod.js +12 -0
  9. package/dist/governance/observe.d.ts +172 -0
  10. package/dist/governance/observe.js +139 -0
  11. package/dist/logical/conformance.d.ts +44 -0
  12. package/dist/logical/conformance.js +108 -0
  13. package/dist/logical/constraints.d.ts +86 -0
  14. package/dist/logical/constraints.js +112 -0
  15. package/dist/logical/exchange.d.ts +98 -0
  16. package/dist/logical/exchange.js +135 -0
  17. package/dist/logical/ledger.d.ts +94 -0
  18. package/dist/logical/ledger.js +90 -0
  19. package/dist/logical/mapping.d.ts +64 -0
  20. package/dist/logical/mapping.js +99 -0
  21. package/dist/logical/mod.d.ts +18 -0
  22. package/dist/logical/mod.js +19 -0
  23. package/dist/logical/observe.d.ts +222 -0
  24. package/dist/logical/observe.js +156 -0
  25. package/dist/logical/plugin.d.ts +91 -0
  26. package/dist/logical/plugin.js +53 -0
  27. package/dist/logical/ports.d.ts +102 -0
  28. package/dist/logical/ports.js +31 -0
  29. package/dist/logical/registry.d.ts +72 -0
  30. package/dist/logical/registry.js +81 -0
  31. package/dist/logical/tree.d.ts +91 -0
  32. package/dist/logical/tree.js +114 -0
  33. package/dist/mod.d.ts +15 -0
  34. package/dist/mod.js +16 -0
  35. package/dist/physical/http/mod.d.ts +54 -0
  36. package/dist/physical/http/mod.js +114 -0
  37. package/dist/physical/transport/mod.d.ts +79 -0
  38. package/dist/physical/transport/mod.js +61 -0
  39. package/dist/surfaces/headless/mod.d.ts +46 -0
  40. package/dist/surfaces/headless/mod.js +258 -0
  41. package/package.json +67 -4
  42. package/src/governance/exchange.ts +220 -0
  43. package/src/governance/ids.ts +92 -0
  44. package/src/governance/mod.ts +12 -0
  45. package/src/governance/observe.ts +226 -0
  46. package/src/logical/conformance.ts +113 -0
  47. package/src/logical/constraints.ts +154 -0
  48. package/src/logical/exchange.ts +184 -0
  49. package/src/logical/ledger.ts +123 -0
  50. package/src/logical/mapping.ts +114 -0
  51. package/src/logical/mod.ts +19 -0
  52. package/src/logical/observe.ts +314 -0
  53. package/src/logical/plugin.ts +102 -0
  54. package/src/logical/ports.ts +89 -0
  55. package/src/logical/registry.ts +93 -0
  56. package/src/logical/tree.ts +153 -0
  57. package/src/mod.ts +16 -0
  58. package/src/physical/http/mod.ts +134 -0
  59. package/src/physical/transport/mod.ts +85 -0
  60. package/src/surfaces/headless/mod.ts +293 -0
@@ -0,0 +1,61 @@
1
+ // Spec: 0004-integrations-physical FR-004, FR-005, FR-006
2
+ /**
3
+ * The transports of exchange (commons integrations 0004-integrations-physical): an `ExchangeTransport` is a port, a record of functions, and this module gives HTTPS on
4
+ * Net's transport (a POST of a document to a partner's endpoint, with a bearer secret), the token request of OAuth2 backend services in the manner of SMART (a client
5
+ * credentials grant with a signed assertion, the signing a port), and the framing of MLLP over TCP. SFTP, AS2 and AS4 are specified and Planned.
6
+ *
7
+ * @remarks
8
+ * What a partner answers is a payload: it is returned to the caller and never put in a failure, a log or a trace; a failure holds a kind and a status.
9
+ *
10
+ * @module
11
+ */
12
+ import { err, ok } from "@intellectual-frontiers/core";
13
+ import { secretOf } from "@intellectual-frontiers/integrations/logical";
14
+ /** HTTPS: a POST of the document to the endpoint, authorized by a bearer secret; a status of 400 or more is `rejected`, with the status only. */
15
+ export function httpsTransport(t, endpoint, bearer) {
16
+ return {
17
+ send: async (m) => {
18
+ const x = await t.send({ method: "POST", url: endpoint, headers: { "content-type": m.contentType, authorization: `Bearer ${bearer.reveal()}` }, body: m.body });
19
+ if (x.kind === "err")
20
+ return err({ kind: x.error.kind });
21
+ return x.value.status >= 400 ? err({ kind: "rejected", status: x.value.status }) : ok({ status: x.value.status, body: x.value.body });
22
+ },
23
+ };
24
+ }
25
+ /** The form of a client credentials request that carries a signed assertion (RFC 7523, as SMART Backend Services uses it). */
26
+ export function backendServicesForm(assertion, scope) {
27
+ const pairs = [
28
+ ["grant_type", "client_credentials"],
29
+ ["client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"],
30
+ ["client_assertion", assertion.reveal()],
31
+ ["scope", scope],
32
+ ];
33
+ return pairs.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
34
+ }
35
+ /** A bearer secret from the token endpoint: it signs an assertion, posts the form and reads `access_token` of the answer. */
36
+ export async function requestToken(t, tokenUrl, signer, claims, scope) {
37
+ const signed = await signer.sign(claims);
38
+ if (signed.kind === "err")
39
+ return err(signed.error);
40
+ const x = await t.send({ method: "POST", url: tokenUrl, headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, body: backendServicesForm(signed.value, scope) });
41
+ if (x.kind === "err")
42
+ return err({ kind: x.error.kind });
43
+ if (x.value.status >= 400)
44
+ return err({ kind: "rejected", status: x.value.status });
45
+ try {
46
+ const body = JSON.parse(x.value.body);
47
+ const token = typeof body === "object" && body !== null && "access_token" in body ? body.access_token : undefined;
48
+ return typeof token === "string" && token !== "" ? ok(secretOf(token)) : err({ kind: "malformed" });
49
+ }
50
+ catch {
51
+ return err({ kind: "malformed" });
52
+ }
53
+ }
54
+ /** MLLP start block, end block and carriage return. */
55
+ export const MLLP = { start: "\u000b", end: "\u001c", cr: "\r" };
56
+ /** A message in the framing of MLLP. */
57
+ export const mllpFrame = (message) => `${MLLP.start}${message}${MLLP.end}${MLLP.cr}`;
58
+ /** The message of a frame, or `undefined` where the text is not one whole frame. */
59
+ export function mllpUnframe(frame) {
60
+ return frame.startsWith(MLLP.start) && frame.endsWith(`${MLLP.end}${MLLP.cr}`) ? frame.slice(1, -2) : undefined;
61
+ }
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The headless verbs of Integrations (commons integrations 0009-integrations-verbs): `integrations observe|probe|check` for connectors and `integrations
3
+ * validate|translate|send|receive|explain` for exchange, as commands of Headless built from the typed cores, with their actions and reach policies declared, their
4
+ * outcome typed, and every outcome passed through the redaction of Headless over the values of the payload so that a payload never appears in what a verb says.
5
+ *
6
+ * @remarks
7
+ * Every effect is a port of `Deps`: the connectors and the way each reaches its system, the files, the transport of an agreement. A verb is a function of them,
8
+ * so that a test runs it over in-memory ports, and a program (the command line, a tool server, a REST interface) draws the same verbs.
9
+ *
10
+ * @module
11
+ */
12
+ import { type Result } from "@intellectual-frontiers/core";
13
+ import { type Command } from "@intellectual-frontiers/headless/logical";
14
+ import { type Clock, type Connector, type CredentialError, type Acknowledgement, type FindingCode, type PluginRegistry, type ReadPort, type Schema, type Terminologies } from "@intellectual-frontiers/integrations/logical";
15
+ import { type AgreementId, type ConnectorId, type ExchangeAgreement } from "@intellectual-frontiers/integrations/governance";
16
+ import type { ExchangeTransport, TransportFailure } from "@intellectual-frontiers/integrations/transport";
17
+ /** Every effect the verbs need, as ports. */
18
+ export type Deps = {
19
+ readonly connectors: ReadonlyMap<ConnectorId, Connector>;
20
+ /** The read port of a connector's system, made from its credential reference at the edge. */
21
+ readonly readPort: (c: Connector) => Promise<Result<ReadPort, CredentialError>>;
22
+ readonly plugins: PluginRegistry;
23
+ readonly schemas: ReadonlyMap<string, Schema>;
24
+ readonly terminologies: Terminologies;
25
+ readonly agreements: ReadonlyMap<AgreementId, ExchangeAgreement>;
26
+ readonly readFile: (path: string) => Promise<Result<string, {
27
+ readonly kind: "not-found";
28
+ }>>;
29
+ readonly writeFile: (path: string, text: string) => Promise<Result<void, {
30
+ readonly kind: "not-writable";
31
+ }>>;
32
+ readonly transportOf: (a: ExchangeAgreement) => Promise<Result<ExchangeTransport, {
33
+ readonly kind: "no-credential";
34
+ }>>;
35
+ readonly clock: Clock;
36
+ };
37
+ /** One sentence for each code of a finding: what `explain` says. */
38
+ export declare const EXPLANATIONS: Readonly<Record<FindingCode, string>>;
39
+ /** The verbs of Integrations. */
40
+ export declare function integrationsCommands(deps: Deps): readonly Command[];
41
+ /** The program node `integrations`, with its verbs. */
42
+ export declare function integrationsBranch(deps: Deps): import("@intellectual-frontiers/headless/logical").Branch;
43
+ /** An acknowledgement's status, re-exported for a surface that draws it. */
44
+ export declare const acknowledgementStatus: (a: Acknowledgement) => import("@intellectual-frontiers/integrations/logical").AckStatus;
45
+ /** Exhaustive over the ways a delivery fails, for a surface that draws them. */
46
+ export declare function describeFailure(f: TransportFailure): string;
@@ -0,0 +1,258 @@
1
+ // Spec: 0009-integrations-verbs FR-001, FR-002, FR-003, FR-004, FR-005
2
+ /**
3
+ * The headless verbs of Integrations (commons integrations 0009-integrations-verbs): `integrations observe|probe|check` for connectors and `integrations
4
+ * validate|translate|send|receive|explain` for exchange, as commands of Headless built from the typed cores, with their actions and reach policies declared, their
5
+ * outcome typed, and every outcome passed through the redaction of Headless over the values of the payload so that a payload never appears in what a verb says.
6
+ *
7
+ * @remarks
8
+ * Every effect is a port of `Deps`: the connectors and the way each reaches its system, the files, the transport of an agreement. A verb is a function of them,
9
+ * so that a test runs it over in-memory ports, and a program (the command line, a tool server, a REST interface) draws the same verbs.
10
+ *
11
+ * @module
12
+ */
13
+ import { absurd } from "@intellectual-frontiers/core";
14
+ import { defineReach, problem, redactor } from "@intellectual-frontiers/headless/governance";
15
+ import { branch, command, outcomeOf, redactOutcome } from "@intellectual-frontiers/headless/logical";
16
+ import { value } from "@intellectual-frontiers/terminal/args";
17
+ import { hasErrors, detect, statusOf, transition, transactionsOf, validate, valuesOf, } from "@intellectual-frontiers/integrations/logical";
18
+ import { parseAgreementId, parseConnectorId } from "@intellectual-frontiers/integrations/governance";
19
+ const READ_ONLY = defineReach({ channels: ["local", "ssh", "mcp", "rest"], readOnly: true, idempotent: true });
20
+ const CHANGES = defineReach({ channels: ["local", "mcp", "rest"] });
21
+ const subject = (id) => problem("fail", `there is no ${id}`, { code: "E010-UNKNOWN" });
22
+ /** One sentence for each code of a finding: what `explain` says. */
23
+ export const EXPLANATIONS = {
24
+ "syntax-error": "The text is not of the syntax: its envelope or structure is broken at the offset named. The text itself is never repeated.",
25
+ "unknown-path": "A path of the document is not one the schema defines.",
26
+ "cardinality-min": "A path occurs fewer times than the schema requires.",
27
+ "cardinality-max": "A path occurs more times than the schema allows.",
28
+ "value-pattern": "A value does not match the pattern the schema or profile gives its path.",
29
+ "value-fixed": "A value is not the one value the profile fixes for its path.",
30
+ "code-not-in-terminology": "A code is not in the terminology its path is bound to.",
31
+ "terminology-unavailable": "The terminology a path is bound to was not loaded, so the code could not be checked.",
32
+ "business-rule": "A rule of the agreement, written as a function of the document, found a fault.",
33
+ "unmapped-source-field": "A field of the source ends in no rule of the mapping: it is neither mapped, carried nor dropped by name.",
34
+ "lossy-mapping": "The mapping drops a field by name: what is dropped, and why, is said, and the mapping loses it.",
35
+ "mapping-target-conflict": "Two sources of a mapping are written to the same place of the target.",
36
+ };
37
+ const isFindingCode = (code) => Object.hasOwn(EXPLANATIONS, code);
38
+ const byLevel = (fs) => fs.map((f) => problem(f.severity === "error" ? "fail" : "warn", f.message, { code: `E${f.level === "syntax" ? "100" : f.level === "schema" ? "110" : f.level === "profile" ? "120" : f.level === "terminology" ? "130" : "140"}-${f.code.toUpperCase().replaceAll("_", "-")}` }));
39
+ async function load(deps, path) {
40
+ const text = await deps.readFile(path);
41
+ if (text.kind === "err")
42
+ return { kind: "err", error: outcomeOf(null, { problems: [problem("fail", `${path} cannot be read`, { code: "E020-READ" })] }) };
43
+ const found = detect(deps.plugins, text.value);
44
+ if (found.kind === "err")
45
+ return { kind: "err", error: outcomeOf(null, { problems: [problem("fail", `${path} is not of a syntax a plugin reads (${found.error.code} at ${found.error.offset})`, { code: "E100-SYNTAX-ERROR" })] }) };
46
+ return { kind: "ok", value: { tree: found.value.tree, pluginId: found.value.plugin.id } };
47
+ }
48
+ /** The scrubbed outcome of a verb over a tree: every value of the payload is masked in everything the outcome says. */
49
+ const scrubbed = (o, tree) => (tree === undefined ? o : redactOutcome(o, redactor(valuesOf(tree).filter((v) => v.length >= 4))));
50
+ /** The verbs of Integrations. */
51
+ export function integrationsCommands(deps) {
52
+ const connectorOf = (name) => {
53
+ const id = parseConnectorId(name ?? "");
54
+ return id.kind === "ok" ? deps.connectors.get(id.value) : undefined;
55
+ };
56
+ const observe = command({
57
+ name: "observe",
58
+ summary: "Observe a system read-only and report the posture, assets and gaps.",
59
+ options: {},
60
+ operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
61
+ action: { kind: "report", reach: READ_ONLY },
62
+ run: async (args) => {
63
+ const c = connectorOf(args.positionals[0]);
64
+ if (c === undefined)
65
+ return outcomeOf(null, { problems: [subject("such connector")] });
66
+ const port = await deps.readPort(c);
67
+ if (port.kind === "err")
68
+ return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL", fix: "integrations probe" })] });
69
+ const o = await c.observe({ port: port.value, now: deps.clock.now() });
70
+ if (o.kind === "err")
71
+ return outcomeOf(null, { problems: [problem("fail", `observing ${c.governance.id} failed: ${o.error.kind}`, { code: "E030-OBSERVE" })] });
72
+ const v = o.value;
73
+ return outcomeOf({ provider: v.provider, account: v.account, at: v.at, assets: v.assets.length, records: v.records?.length ?? 0, gaps: v.gaps, posture: v.posture }, { text: `${v.provider}: ${v.assets.length} assets, ${v.gaps.length} gaps` });
74
+ },
75
+ });
76
+ const probe = command({
77
+ name: "probe",
78
+ summary: "Check that a connector's credential reaches its system, reading one thing.",
79
+ options: {},
80
+ operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
81
+ action: { kind: "report", reach: READ_ONLY },
82
+ run: async (args) => {
83
+ const c = connectorOf(args.positionals[0]);
84
+ if (c === undefined)
85
+ return outcomeOf(null, { problems: [subject("such connector")] });
86
+ const port = await deps.readPort(c);
87
+ if (port.kind === "err")
88
+ return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL" })] });
89
+ const r = await c.probe({ port: port.value, now: deps.clock.now() });
90
+ return r.kind === "ok" ? outcomeOf({ reachable: true, account: r.value.account }, { text: `${c.governance.id} reaches ${r.value.account}` }) : outcomeOf(null, { problems: [problem("fail", `the probe of ${c.governance.id} failed: ${r.error.kind}`, { code: "E031-PROBE" })] });
91
+ },
92
+ });
93
+ const check = command({
94
+ name: "check",
95
+ summary: "Observe and judge the posture policies of a connector.",
96
+ options: {},
97
+ operands: [{ name: "CONNECTOR", help: "The id of a connector.", arity: "one" }],
98
+ action: { kind: "report", reach: READ_ONLY },
99
+ run: async (args) => {
100
+ const c = connectorOf(args.positionals[0]);
101
+ if (c === undefined)
102
+ return outcomeOf(null, { problems: [subject("such connector")] });
103
+ const port = await deps.readPort(c);
104
+ if (port.kind === "err")
105
+ return outcomeOf(null, { problems: [problem("pending", `the credential ${c.governance.credential.ref} is not available (${port.error.kind})`, { code: "P010-CREDENTIAL" })] });
106
+ const now = deps.clock.now();
107
+ const o = await c.observe({ port: port.value, now });
108
+ if (o.kind === "err")
109
+ return outcomeOf(null, { problems: [problem("fail", `observing ${c.governance.id} failed: ${o.error.kind}`, { code: "E030-OBSERVE" })] });
110
+ const results = c.check(o.value, now);
111
+ const problems = results.flatMap((r) => (r.status === "fail" ? [problem("fail", `${r.id}: ${r.detail}`, { fix: r.fix, code: "E032-POSTURE" })] : r.status === "warn" ? [problem("warn", `${r.id}: ${r.detail}`, { fix: r.fix })] : []));
112
+ return outcomeOf({ results }, { problems, text: `${results.filter((r) => r.status === "pass").length} of ${results.length} policies pass` });
113
+ },
114
+ });
115
+ const validateVerb = command({
116
+ name: "validate",
117
+ summary: "Validate a document against a schema: syntax, schema and terminology findings, never the values.",
118
+ options: { schema: value({ help: "The id of the schema to validate against.", required: true }) },
119
+ operands: [{ name: "FILE", help: "The document.", arity: "one" }],
120
+ action: { kind: "report", reach: READ_ONLY },
121
+ run: async (args) => {
122
+ const loaded = await load(deps, args.positionals[0] ?? "");
123
+ if (loaded.kind === "err")
124
+ return loaded.error;
125
+ const schema = deps.schemas.get(args.options.schema);
126
+ if (schema === undefined)
127
+ return outcomeOf(null, { problems: [subject(`schema ${args.options.schema}`)] });
128
+ const findings = transactionsOf(loaded.value.tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
129
+ return scrubbed(outcomeOf({ findings, valid: !hasErrors(findings), transactions: transactionsOf(loaded.value.tree).length }, { problems: byLevel(findings), text: hasErrors(findings) ? `${findings.length} findings` : "valid" }), loaded.value.tree);
130
+ },
131
+ });
132
+ const translate = command({
133
+ name: "translate",
134
+ summary: "Report what translating a document to another syntax would do; the document itself is written only to --out.",
135
+ options: { out: value({ help: "Where to write the translated document." }) },
136
+ operands: [{ name: "FILE", help: "The document.", arity: "one" }],
137
+ action: { kind: "action", effect: "mutate", idempotent: true, reach: CHANGES },
138
+ run: async (args) => {
139
+ const loaded = await load(deps, args.positionals[0] ?? "");
140
+ if (loaded.kind === "err")
141
+ return loaded.error;
142
+ const plugin = [...deps.plugins.values()].find((p) => p.id === loaded.value.pluginId);
143
+ const written = plugin === undefined ? undefined : plugin.codec.serialize(loaded.value.tree);
144
+ if (written === undefined || written.kind === "err")
145
+ return outcomeOf(null, { problems: [problem("fail", "the document cannot be written", { code: "E101-SERIALIZE" })] });
146
+ if (args.options.out !== undefined) {
147
+ const w = await deps.writeFile(args.options.out, written.value);
148
+ if (w.kind === "err")
149
+ return scrubbed(outcomeOf(null, { problems: [problem("fail", `${args.options.out} cannot be written`, { code: "E021-WRITE" })] }), loaded.value.tree);
150
+ }
151
+ return scrubbed(outcomeOf({ transactions: transactionsOf(loaded.value.tree).length, wrote: args.options.out !== undefined }, { text: "translated" }), loaded.value.tree);
152
+ },
153
+ });
154
+ const agreementOf = (name) => {
155
+ const id = parseAgreementId(name);
156
+ return id.kind === "ok" ? deps.agreements.get(id.value) : undefined;
157
+ };
158
+ const send = command({
159
+ name: "send",
160
+ summary: "Send a document to a partner under an agreement: validate, deliver, and say where the exchange stands.",
161
+ options: { agreement: value({ help: "The id of the agreement.", required: true }), schema: value({ help: "The id of the schema to validate against." }) },
162
+ operands: [{ name: "FILE", help: "The document.", arity: "one" }],
163
+ action: { kind: "action", effect: "mutate", reach: CHANGES },
164
+ run: async (args) => {
165
+ const a = agreementOf(args.options.agreement);
166
+ if (a === undefined)
167
+ return outcomeOf(null, { problems: [subject(`agreement ${args.options.agreement}`)] });
168
+ const loaded = await load(deps, args.positionals[0] ?? "");
169
+ if (loaded.kind === "err")
170
+ return loaded.error;
171
+ const tree = loaded.value.tree;
172
+ const schema = args.options.schema === undefined ? undefined : deps.schemas.get(args.options.schema);
173
+ const findings = schema === undefined ? [] : transactionsOf(tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
174
+ if (hasErrors(findings))
175
+ return scrubbed(outcomeOf({ findings, state: "pending" }, { problems: byLevel(findings) }), tree);
176
+ const plugin = [...deps.plugins.values()].find((p) => p.id === loaded.value.pluginId);
177
+ const text = plugin === undefined ? undefined : plugin.codec.serialize(tree);
178
+ if (text === undefined || text.kind === "err")
179
+ return scrubbed(outcomeOf(null, { problems: [problem("fail", "the document cannot be written", { code: "E101-SERIALIZE" })] }), tree);
180
+ const transport = await deps.transportOf(a);
181
+ if (transport.kind === "err")
182
+ return scrubbed(outcomeOf(null, { problems: [problem("pending", `the credential ${a.credential} is not available`, { code: "P010-CREDENTIAL" })] }), tree);
183
+ const sent = await transport.value.send({ contentType: "application/octet-stream", body: text.value });
184
+ const at = deps.clock.now();
185
+ let state = { kind: "pending" };
186
+ const s1 = transition(state, { kind: "send", at }, a.serviceLevels);
187
+ if (s1.kind === "ok")
188
+ state = s1.value;
189
+ if (sent.kind === "err") {
190
+ const s2 = transition(state, { kind: "timeout" }, a.serviceLevels);
191
+ if (s2.kind === "ok")
192
+ state = s2.value;
193
+ return scrubbed(outcomeOf({ state: state.kind, failure: sent.error.kind }, { problems: [problem("fail", `the partner was not reached (${sent.error.kind})`, { code: "E040-DELIVERY" })] }), tree);
194
+ }
195
+ return scrubbed(outcomeOf({ state: state.kind, status: sent.value.status }, { text: `sent to ${a.partner}` }), tree);
196
+ },
197
+ });
198
+ const receive = command({
199
+ name: "receive",
200
+ summary: "Receive a document under an agreement: read it, validate it and say what acknowledgement is due.",
201
+ options: { agreement: value({ help: "The id of the agreement.", required: true }), schema: value({ help: "The id of the schema to validate against." }) },
202
+ operands: [{ name: "FILE", help: "The document.", arity: "one" }],
203
+ action: { kind: "action", effect: "mutate", idempotent: true, reach: CHANGES },
204
+ run: async (args) => {
205
+ const a = agreementOf(args.options.agreement);
206
+ if (a === undefined)
207
+ return outcomeOf(null, { problems: [subject(`agreement ${args.options.agreement}`)] });
208
+ const loaded = await load(deps, args.positionals[0] ?? "");
209
+ if (loaded.kind === "err")
210
+ return loaded.error;
211
+ const tree = loaded.value.tree;
212
+ const schema = args.options.schema === undefined ? undefined : deps.schemas.get(args.options.schema);
213
+ const findings = schema === undefined ? [] : transactionsOf(tree).flatMap((t) => validate(t, schema, { terminologies: deps.terminologies }));
214
+ const ackStatus = hasErrors(findings) ? "rejected" : findings.length > 0 ? "accepted-with-errors" : "accepted";
215
+ let state = { kind: "pending" };
216
+ const r = transition(state, { kind: "receive", at: deps.clock.now() }, a.serviceLevels);
217
+ if (r.kind === "ok")
218
+ state = r.value;
219
+ const next = transition(state, { kind: "ack", status: ackStatus }, a.serviceLevels);
220
+ if (next.kind === "ok")
221
+ state = next.value;
222
+ const due = a.acknowledgements.map((x) => x.kind);
223
+ return scrubbed(outcomeOf({ findings, state: state.kind, acknowledge: ackStatus, due }, { problems: byLevel(findings), text: `received from ${a.partner}: ${ackStatus}` }), tree);
224
+ },
225
+ });
226
+ const explain = command({
227
+ name: "explain",
228
+ summary: "Explain a finding code, or what an acknowledgement means.",
229
+ options: {},
230
+ operands: [{ name: "CODE", help: "A finding code, such as cardinality-min.", arity: "one" }],
231
+ action: { kind: "report", reach: READ_ONLY },
232
+ run: (args) => {
233
+ const code = args.positionals[0] ?? "";
234
+ const text = isFindingCode(code) ? EXPLANATIONS[code] : undefined;
235
+ return Promise.resolve(text === undefined ? outcomeOf(null, { problems: [subject(`code ${code}`)] }) : outcomeOf({ code, explanation: text }, { text }));
236
+ },
237
+ });
238
+ return [observe, probe, check, validateVerb, translate, send, receive, explain];
239
+ }
240
+ /** The program node `integrations`, with its verbs. */
241
+ export function integrationsBranch(deps) {
242
+ return branch({ name: "integrations", summary: "Observe systems read-only and exchange documents under standards.", children: integrationsCommands(deps) });
243
+ }
244
+ /** An acknowledgement's status, re-exported for a surface that draws it. */
245
+ export const acknowledgementStatus = (a) => statusOf(a);
246
+ /** Exhaustive over the ways a delivery fails, for a surface that draws them. */
247
+ export function describeFailure(f) {
248
+ switch (f.kind) {
249
+ case "refused":
250
+ return "the request was refused before it was sent";
251
+ case "network":
252
+ return "the network gave no answer";
253
+ case "rejected":
254
+ return `the partner rejected it with status ${f.status}`;
255
+ default:
256
+ return absurd(f);
257
+ }
258
+ }
package/package.json CHANGED
@@ -1,6 +1,69 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/integrations",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Integrations in the layers of Kanon: connectors that observe the outside world read-only (clouds, SaaS, identity, code hosts, HR, endpoints, network devices) and exchanges of messages and documents under standards and partner agreements (FHIR, X12, HL7 v2), with each standard a plugin package behind typed ports and a conformance suite.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "engines": {
8
+ "node": ">=26"
9
+ },
10
+ "sideEffects": false,
11
+ "types": "./dist/mod.d.ts",
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/mod.d.ts",
15
+ "bun": "./src/mod.ts",
16
+ "default": "./dist/mod.js"
17
+ },
18
+ "./governance": {
19
+ "types": "./dist/governance/mod.d.ts",
20
+ "bun": "./src/governance/mod.ts",
21
+ "default": "./dist/governance/mod.js"
22
+ },
23
+ "./logical": {
24
+ "types": "./dist/logical/mod.d.ts",
25
+ "bun": "./src/logical/mod.ts",
26
+ "default": "./dist/logical/mod.js"
27
+ },
28
+ "./http": {
29
+ "types": "./dist/physical/http/mod.d.ts",
30
+ "bun": "./src/physical/http/mod.ts",
31
+ "default": "./dist/physical/http/mod.js"
32
+ },
33
+ "./transport": {
34
+ "types": "./dist/physical/transport/mod.d.ts",
35
+ "bun": "./src/physical/transport/mod.ts",
36
+ "default": "./dist/physical/transport/mod.js"
37
+ },
38
+ "./headless": {
39
+ "types": "./dist/surfaces/headless/mod.d.ts",
40
+ "bun": "./src/surfaces/headless/mod.ts",
41
+ "default": "./dist/surfaces/headless/mod.js"
42
+ }
43
+ },
44
+ "dependencies": {
45
+ "@intellectual-frontiers/core": "0.1.4",
46
+ "@intellectual-frontiers/grc": "0.2.0",
47
+ "@intellectual-frontiers/headless": "0.3.0",
48
+ "@intellectual-frontiers/net": "0.1.5",
49
+ "@intellectual-frontiers/terminal": "0.1.6"
50
+ },
51
+ "files": [
52
+ "dist",
53
+ "src",
54
+ "README.md",
55
+ "LICENSE"
56
+ ],
57
+ "repository": {
58
+ "type": "git",
59
+ "url": "git+https://github.com/intellectual-frontiers/.github.git",
60
+ "directory": "commons/integrations"
61
+ },
62
+ "homepage": "https://github.com/intellectual-frontiers/.github/tree/main/commons/integrations",
63
+ "bugs": {
64
+ "url": "https://github.com/intellectual-frontiers/.github/issues"
65
+ },
66
+ "publishConfig": {
67
+ "access": "public"
68
+ }
69
+ }