@ptkl/toolkit 0.14.0 → 1.0.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.
@@ -0,0 +1,146 @@
1
+ import { Command } from "commander";
2
+ import { Satellites } from "@ptkl/sdk/beta";
3
+ import * as sdk from "../lib/sdk.js";
4
+ import { registerCommand, withProfile } from "../lib/scaffold.js";
5
+ import payments from "./integrations/payments.js";
6
+ // Typed interface subtrees (WP-121…125) attach themselves via `integrationSub()` when their
7
+ // `register()` is invoked below — imported here (rather than from src/commands/index.ts, which is
8
+ // out of this WP's sanctioned paths) so `ptkl integration` stays the single wiring point for its
9
+ // own subtree, per the module comment above. Circular-safe: `mail` only calls back into
10
+ // `isActive`/`integrationSub` from inside its own `register()`, which this file invokes after
11
+ // both modules have finished evaluating.
12
+ import mail from "./integrations/mail.js";
13
+ import dms from "./integrations/dms.js";
14
+ import timber from "./integrations/timber.js";
15
+ import serbia from "./integrations/serbia.js";
16
+ /** `ptkl integration` — the integrations gateway (RFC §4.3 / §6.1). Integrations are installed +
17
+ * activated **per project** (subscription-gated), so they live under one namespace instead of as
18
+ * flat top-level commands — mirroring the SDK exactly: `Integrations` (`@ptkl/sdk/beta`) is a
19
+ * façade mapping an id -> typed client via `getInterfaceOf(id)`, with uniform
20
+ * `list()`/`isInstalled()`/`isActive()`.
21
+ *
22
+ * Three invocation layers (RFC §6.1):
23
+ * 1. Lifecycle (this file) — uniform for every integration: list/install/uninstall/
24
+ * activate/deactivate/onboarding/marketplace/explore.
25
+ * 2. Typed interfaces (WP-121…125: payments/mail/dms/timber/serbia) — attached to the shared
26
+ * `integration` command via `integrationSub()` below.
27
+ * 3. Generic passthrough (this file's `run`) — satellite JSON-RPC execute, for satellites and
28
+ * anything without a typed client. Same door as `ptkl satellite execute`.
29
+ */
30
+ // The shared `integration` command instance. Built once at module load so later interface
31
+ // subtrees (WP-121…125) can attach to it regardless of module-import order — see `integrationSub`.
32
+ const integrationCommand = new Command("integration").description("Manage platform integrations: lifecycle (install/activate/…), typed interfaces and generic run");
33
+ /** Shared attach point for the typed interface subtrees added by later WPs (payments/mail/dms/
34
+ * timber/serbia — WP-121…125). Each of those WPs builds its own `Command` (e.g. `new
35
+ * Command("payments")...`) the same way any other command group is built, then calls
36
+ * `integrationSub(cmd)` once to graft it onto `ptkl integration` — instead of editing this file.
37
+ *
38
+ * ```ts
39
+ * // src/commands/integration/payments.ts
40
+ * import { integrationSub } from "../integration.js";
41
+ * const cmd = new Command("payments").description("...");
42
+ * cmd.addCommand(...);
43
+ * integrationSub(cmd);
44
+ * ```
45
+ *
46
+ * Returns the same command that was passed in, so the call can be chained/exported if useful. */
47
+ export function integrationSub(sub) {
48
+ integrationCommand.addCommand(sub);
49
+ return sub;
50
+ }
51
+ function parseJSON(label, raw) {
52
+ try {
53
+ return JSON.parse(raw);
54
+ }
55
+ catch {
56
+ console.error(`${label} must be valid JSON`);
57
+ process.exit(1);
58
+ }
59
+ }
60
+ function satellites(profile) {
61
+ return new Satellites(sdk.integrationsOptions(profile));
62
+ }
63
+ /** Precheck used by the typed interface subcommands (WP-121…125) before calling through to a
64
+ * provider. Installed-but-inactive integrations 403 at the API; this turns that into the friendly
65
+ * hint from RFC §6.1 instead, so the install/activate requirement is discoverable rather than
66
+ * surfacing as a raw 403. Exits the process (matching `withProfile`'s error handling) when the
67
+ * integration isn't active for the current project. */
68
+ export async function isActive(profile, id) {
69
+ const active = await sdk.integrations(profile).isActive(id);
70
+ if (!active) {
71
+ console.error(`${id} is not active for this project — run \`ptkl integration activate ${id}\``);
72
+ process.exit(1);
73
+ }
74
+ }
75
+ class IntegrationCommand {
76
+ register() {
77
+ const cmd = integrationCommand;
78
+ cmd.addCommand(registerCommand(new Command("list").description("List integrations installed on the current project")).action(withProfile(async (profile) => {
79
+ return await sdk.integrations(profile).list();
80
+ })));
81
+ cmd.addCommand(registerCommand(new Command("install")
82
+ .description("Install an integration on the current project")
83
+ .argument("<id>", "Integration id, e.g. protokol-payments")
84
+ .option("-d, --data <json>", "Optional install-time configuration payload as a JSON string")).action(withProfile(async (profile, id, opts) => {
85
+ const data = opts.data ? parseJSON("--data", opts.data) : undefined;
86
+ return await sdk.integrations(profile).install(id, data);
87
+ })));
88
+ cmd.addCommand(registerCommand(new Command("uninstall")
89
+ .description("Uninstall an integration from the current project")
90
+ .argument("<id>", "Integration id")).action(withProfile(async (profile, id) => {
91
+ return await sdk.integrations(profile).uninstall(id);
92
+ })));
93
+ cmd.addCommand(registerCommand(new Command("activate")
94
+ .description("Activate an installed integration")
95
+ .argument("<id>", "Integration id")).action(withProfile(async (profile, id) => {
96
+ return await sdk.integrations(profile).activate(id);
97
+ })));
98
+ cmd.addCommand(registerCommand(new Command("deactivate")
99
+ .description("Deactivate an installed integration")
100
+ .argument("<id>", "Integration id")).action(withProfile(async (profile, id) => {
101
+ return await sdk.integrations(profile).deactivate(id);
102
+ })));
103
+ cmd.addCommand(registerCommand(new Command("onboarding")
104
+ .description("Advance/update the onboarding state of an installed integration")
105
+ .argument("<id>", "Integration id")
106
+ .requiredOption("-s, --step <step>", "Onboarding step id")
107
+ .option("-d, --data <json>", "Optional step payload as a JSON string")).action(withProfile(async (profile, id, opts) => {
108
+ const data = opts.data ? parseJSON("--data", opts.data) : undefined;
109
+ return await sdk.integrations(profile).onboarding(id, {
110
+ step: opts.step,
111
+ ...(data !== undefined ? { data } : {}),
112
+ });
113
+ })));
114
+ cmd.addCommand(registerCommand(new Command("marketplace").description("List marketplace-available integrations (subscription/geo aware)")).action(withProfile(async (profile) => {
115
+ return await sdk.integrations(profile).marketplace();
116
+ })));
117
+ cmd.addCommand(registerCommand(new Command("explore").description("List explorable integration templates (subscription/geo aware)")).action(withProfile(async (profile) => {
118
+ return await sdk.integrations(profile).explore();
119
+ })));
120
+ cmd.addCommand(this.registerRun());
121
+ // Typed interface subtrees (WP-121…125) — each grafts itself onto `cmd` via
122
+ // `integrationSub()` when its own `.register()` runs.
123
+ payments.register();
124
+ mail.register();
125
+ dms.register();
126
+ timber.register();
127
+ serbia.register();
128
+ return cmd;
129
+ }
130
+ /** Generic passthrough: `ptkl integration run <id> <method> --params '{"inputs":{…}}'` ->
131
+ * `satellites/{id}/commands/{method}/execute` (JSON-RPC 2.0). Same door as `ptkl satellite
132
+ * execute` (RFC §6.1, layer 3) — the fallback for satellites and any provider without a typed
133
+ * client. */
134
+ registerRun() {
135
+ return registerCommand(new Command("run")
136
+ .description("Invoke a satellite command on an integration (generic JSON-RPC passthrough)")
137
+ .argument("<id>", "Integration/satellite id")
138
+ .argument("<method>", "Command name to execute")
139
+ .option("-p, --params <json>", "Execute payload as a JSON string ({ inputs, context, session, caller_prn }), defaults to {}")).action(withProfile(async (profile, id, method, opts) => {
140
+ await isActive(profile, id);
141
+ const payload = opts.params ? parseJSON("--params", opts.params) : {};
142
+ return await satellites(profile).execute(id, method, payload);
143
+ }));
144
+ }
145
+ }
146
+ export default new IntegrationCommand();