@ptkl/toolkit 0.11.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.
package/README.md CHANGED
@@ -124,6 +124,107 @@ You can override the active profile for any command using the global `--profile`
124
124
  ptkl --profile production apps upload -a app -d ./my-app
125
125
  ```
126
126
 
127
+ ## Forge
128
+
129
+ Commands for building and running Protokol Forge apps locally.
130
+
131
+ ### `ptkl forge dev`
132
+
133
+ Start a local development server for a forge app with hot module replacement.
134
+
135
+ ```bash
136
+ ptkl forge dev -p <path> [options]
137
+ ```
138
+
139
+ #### Options
140
+
141
+ | Flag | Description |
142
+ |------|-------------|
143
+ | `-p, --path <path>` | **(required)** Path to the app directory |
144
+ | `--view <view>` | Which view to serve (defaults to `main`) |
145
+ | `--platform-url <url>` | Platform UI URL for consent/permission flows |
146
+ | `-m, --mode <mode>` | Vite mode (defaults to `development`) |
147
+ | `--env <env>` | Target environment (`dev` or `live`) |
148
+
149
+ #### Multi-view development
150
+
151
+ Forge apps can declare multiple views in `ptkl.config.js`:
152
+
153
+ ```js
154
+ export default {
155
+ name: 'my-app',
156
+ views: {
157
+ main: path.resolve(__dirname, 'src/main.tsx'),
158
+ 'product-details': {
159
+ entry: path.resolve(__dirname, 'src/productDetails.tsx'),
160
+ access: 'public',
161
+ permissions: ['read my-integration::items'],
162
+ },
163
+ },
164
+ }
165
+ ```
166
+
167
+ By default, `ptkl forge dev` serves the `main` view. Use `--view` to serve a different one:
168
+
169
+ ```bash
170
+ # Serve the main platform view (default)
171
+ ptkl forge dev -p .
172
+
173
+ # Serve a public view for standalone testing
174
+ ptkl forge dev -p . --view product-details
175
+ ```
176
+
177
+ The `--view` flag swaps the entry point in the app's `index.html` so Vite serves the selected view with full HMR. Each view runs as a standalone app on its own dev server.
178
+
179
+ Embeddable platform views (not `main`, not `public`) are automatically built in watch mode and published to the local dev hub for cross-app testing via `AppView`.
180
+
181
+ ### `ptkl forge bundle`
182
+
183
+ Build and optionally upload a forge app bundle.
184
+
185
+ ```bash
186
+ ptkl forge bundle -p <path> [options]
187
+ ```
188
+
189
+ #### Options
190
+
191
+ | Flag | Description |
192
+ |------|-------------|
193
+ | `-p, --path <path>` | **(required)** Path to the app directory |
194
+ | `-u, --upload` | Upload the bundle after building |
195
+ | `-m, --mode <mode>` | Vite build mode (defaults to `production`) |
196
+
197
+ ### `ptkl forge list`
198
+
199
+ List all forge apps in the current profile's project.
200
+
201
+ ```bash
202
+ ptkl forge list
203
+ ```
204
+
205
+ ### `ptkl forge install` / `ptkl forge uninstall`
206
+
207
+ Dry-run install or uninstall scripts locally against the active profile.
208
+
209
+ ```bash
210
+ ptkl forge install -p <path> [--env dev|live] [-b]
211
+ ptkl forge uninstall -p <path> [--env dev|live] [-b]
212
+ ```
213
+
214
+ | Flag | Description |
215
+ |------|-------------|
216
+ | `-p, --path <path>` | **(required)** Path to the app directory |
217
+ | `--env <env>` | Run for a specific env only (omit to run both) |
218
+ | `-b, --bundle` | Build the bundle before running the script |
219
+
220
+ ### `ptkl forge remove-version`
221
+
222
+ Remove a specific version of a forge app.
223
+
224
+ ```bash
225
+ ptkl forge remove-version -r <ref> -v <version>
226
+ ```
227
+
127
228
  ## Version
128
229
 
129
230
  Current version: 0.7.0
File without changes
@@ -0,0 +1,111 @@
1
+ import { resolve } from "path";
2
+ import { writeFileSync } from "fs";
3
+ import { Command } from "commander";
4
+ import * as sdk from "../lib/sdk.js";
5
+ import { registerCommand, withEnvOption, withProfile } from "../lib/scaffold.js";
6
+ /** `ptkl billing` — subscriptions, invoices, credits/balance, usage pricing and per-project
7
+ * billing-mode overrides (RFC §6 "Billing": `subscriptions invoices invoice-pdf balance topup
8
+ * credits prices billing-modes`). Maps onto the SDK `Transactions` client (@ptkl/sdk/beta),
9
+ * reached via `platform.billing()` (an alias of `platform.transactions()`) — the
10
+ * `transactions/…` gateway prefix. This is the **billing** service, not distributed/database
11
+ * transactions (see RFC §5(c)). */
12
+ function parseJSON(label, raw) {
13
+ try {
14
+ return JSON.parse(raw);
15
+ }
16
+ catch {
17
+ console.error(`${label} must be valid JSON`);
18
+ process.exit(1);
19
+ }
20
+ }
21
+ class BillingCommand {
22
+ register() {
23
+ const cmd = new Command("billing").description("Manage billing: subscriptions, invoices, balance/credits and pricing");
24
+ cmd.addCommand(registerCommand(new Command("subscriptions").description("List all subscriptions (including expired) for the current project")).action(withProfile(async (profile) => {
25
+ const res = await sdk.platform(profile).billing().getSubscriptions();
26
+ return res.data;
27
+ })));
28
+ cmd.addCommand(registerCommand(new Command("invoices")
29
+ .description("List invoices for the current project, or get a single invoice by uuid")
30
+ .argument("[uuid]", "Invoice uuid — omit to list all invoices")).action(withProfile(async (profile, uuid) => {
31
+ const client = sdk.platform(profile).billing();
32
+ const res = uuid ? await client.getInvoice(uuid) : await client.getInvoices();
33
+ return res.data;
34
+ })));
35
+ cmd.addCommand(this.registerInvoicePdf());
36
+ cmd.addCommand(registerCommand(new Command("balance").description("Get the current project's credit balance")).action(withProfile(async (profile) => {
37
+ const res = await sdk.platform(profile).billing().getBalance();
38
+ return res.data;
39
+ })));
40
+ cmd.addCommand(registerCommand(new Command("topup")
41
+ .description("Generate a checkout link to top up the project's credit balance")
42
+ .requiredOption("-a, --amount-cents <cents>", "Purchase amount in USD cents (e.g. 1000 = $10.00)")
43
+ .option("-c, --currency <currency>", "ISO 4217 currency code (defaults to USD server-side)")).action(withProfile(async (profile, opts) => {
44
+ const res = await sdk.platform(profile).billing().topUp({
45
+ amount_cents: Number(opts.amountCents),
46
+ ...(opts.currency ? { currency: opts.currency } : {}),
47
+ });
48
+ return res.data;
49
+ })));
50
+ cmd.addCommand(registerCommand(new Command("credits")
51
+ .description("Get the project's credit activity (deductions/top-ups) history")
52
+ .option("-l, --limit <n>", "Max rows to return (server default 50, capped at 200)")
53
+ .option("--offset <n>", "Row offset for pagination")
54
+ .option("-t, --type <type>", "Filter by entry type (e.g. deduction | topup)")
55
+ .option("-y, --year <year>", "Filter by year")
56
+ .option("-m, --month <month>", "Filter by month")).action(withProfile(async (profile, opts) => {
57
+ const query = {
58
+ ...(opts.limit !== undefined ? { limit: Number(opts.limit) } : {}),
59
+ ...(opts.offset !== undefined ? { offset: Number(opts.offset) } : {}),
60
+ ...(opts.type ? { type: opts.type } : {}),
61
+ ...(opts.year !== undefined ? { year: Number(opts.year) } : {}),
62
+ ...(opts.month !== undefined ? { month: Number(opts.month) } : {}),
63
+ };
64
+ const res = await sdk.platform(profile).billing().getCreditsHistory(query);
65
+ return res.data;
66
+ })));
67
+ cmd.addCommand(registerCommand(new Command("prices")
68
+ .description("Get the usage-based pricing table for a given currency")
69
+ .requiredOption("-c, --currency <currency>", "ISO 4217 currency code, e.g. USD or RSD")).action(withProfile(async (profile, opts) => {
70
+ const res = await sdk.platform(profile).billing().getPrices(opts.currency);
71
+ return res.data;
72
+ })));
73
+ cmd.addCommand(registerCommand(new Command("billing-modes")
74
+ .description("Get the project's usage-billing-mode overrides, or set one with --option-code/--mode/--data")
75
+ .option("--option-code <code>", "Usage option code to update (requires --mode, or use --data)")
76
+ .option("--mode <mode>", "Billing mode to set: credits | hybrid | invoice (requires --option-code)")
77
+ .option("-d, --data <json>", "Update payload as a JSON string ({ option_code, mode }) — alternative to --option-code/--mode")).action(withProfile(async (profile, opts) => {
78
+ const client = sdk.platform(profile).billing();
79
+ if (opts.data) {
80
+ const payload = parseJSON("--data", opts.data);
81
+ const res = await client.updateBillingModes(payload);
82
+ return res.data;
83
+ }
84
+ if (opts.optionCode || opts.mode) {
85
+ if (!opts.optionCode || !opts.mode) {
86
+ console.error("--option-code and --mode must be provided together");
87
+ process.exit(1);
88
+ }
89
+ const res = await client.updateBillingModes({ option_code: opts.optionCode, mode: opts.mode });
90
+ return res.data;
91
+ }
92
+ const res = await client.getBillingModes();
93
+ return res.data;
94
+ })));
95
+ return cmd;
96
+ }
97
+ registerInvoicePdf() {
98
+ const pdfCmd = withEnvOption(new Command("invoice-pdf")
99
+ .description("Download an invoice as a PDF")
100
+ .argument("<uuid>", "Invoice uuid")
101
+ .requiredOption("-o, --out <file>", "File path to write the PDF to"));
102
+ pdfCmd.action(withProfile(async (profile, uuid, opts) => {
103
+ const res = await sdk.platform(profile).billing().getInvoicePdf(uuid);
104
+ const outPath = resolve(opts.out);
105
+ writeFileSync(outPath, Buffer.from(res.data));
106
+ console.log(`Invoice PDF written to ${outPath}`);
107
+ }));
108
+ return pdfCmd;
109
+ }
110
+ }
111
+ export default new BillingCommand();
@@ -0,0 +1,33 @@
1
+ import { Command } from "commander";
2
+ import * as sdk from "../lib/sdk.js";
3
+ import { registerCommand, withProfile } from "../lib/scaffold.js";
4
+ /** `ptkl config` — per-user configuration (RFC §4.1 "Config": `GET/PUT config/user`).
5
+ * Maps 1:1 onto the SDK `Config` client (@ptkl/sdk/beta). */
6
+ function parseJSON(label, raw) {
7
+ try {
8
+ return JSON.parse(raw);
9
+ }
10
+ catch {
11
+ console.error(`${label} must be valid JSON`);
12
+ process.exit(1);
13
+ }
14
+ }
15
+ class ConfigCommand {
16
+ register() {
17
+ const cmd = new Command("config").description("Get or set the current user's configuration");
18
+ cmd.addCommand(registerCommand(new Command("get").description("Get the current user's configuration")).action(withProfile(async (profile) => {
19
+ const res = await sdk.config(profile).getUserConfig();
20
+ return res.data;
21
+ })));
22
+ cmd.addCommand(registerCommand(new Command("set")
23
+ .description("Update the current user's configuration")
24
+ .requiredOption("-p, --path <path>", "Config path to write")
25
+ .requiredOption("-d, --data <json>", "Config data as a JSON string")).action(withProfile(async (profile, opts) => {
26
+ const data = parseJSON("--data", opts.data);
27
+ const res = await sdk.config(profile).updateUserConfig({ path: opts.path, data });
28
+ return res.data;
29
+ })));
30
+ return cmd;
31
+ }
32
+ }
33
+ export default new ConfigCommand();