@edena-solutions/cli 0.0.0-stage → 0.1.0-beta.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/LICENSE +21 -0
- package/README.md +101 -2
- package/dist/src/args.js +56 -0
- package/dist/src/cli.js +164 -0
- package/dist/src/commands/api.js +55 -0
- package/dist/src/commands/auth.js +115 -0
- package/dist/src/commands/docs.js +92 -0
- package/dist/src/commands/listen.js +155 -0
- package/dist/src/commands/logs.js +49 -0
- package/dist/src/commands/open.js +43 -0
- package/dist/src/commands/operation.js +216 -0
- package/dist/src/commands/skill.js +66 -0
- package/dist/src/config.js +105 -0
- package/dist/src/errors.js +52 -0
- package/dist/src/http.js +83 -0
- package/dist/src/output.js +83 -0
- package/dist/src/reference.js +181 -0
- package/dist/src/schema.js +213 -0
- package/dist/src/sse.js +98 -0
- package/dist/src/version.js +14 -0
- package/package.json +44 -4
- package/skill/SKILL.md +60 -0
package/dist/src/sse.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { ApiError } from "./errors.js";
|
|
2
|
+
import { VERSION } from "./version.js";
|
|
3
|
+
const sleep = (ms, signal) => new Promise((resolve) => {
|
|
4
|
+
const timer = setTimeout(resolve, ms);
|
|
5
|
+
signal.addEventListener("abort", () => {
|
|
6
|
+
clearTimeout(timer);
|
|
7
|
+
resolve();
|
|
8
|
+
});
|
|
9
|
+
});
|
|
10
|
+
/**
|
|
11
|
+
* Follows a server-sent events stream of the API until `signal` aborts: messages in order, and when the
|
|
12
|
+
* connection ends (the API closes each after a few minutes, or the network drops) it reconnects with
|
|
13
|
+
* `Last-Event-ID`, so nothing is missed or repeated. A refusal (401, 403, 404) is not retried.
|
|
14
|
+
*/
|
|
15
|
+
export async function followStream(options) {
|
|
16
|
+
let lastId = null;
|
|
17
|
+
let retryMs = 3000;
|
|
18
|
+
let failures = 0;
|
|
19
|
+
let opened = false;
|
|
20
|
+
while (!options.signal.aborted) {
|
|
21
|
+
try {
|
|
22
|
+
const response = await fetch(options.url, {
|
|
23
|
+
headers: {
|
|
24
|
+
Accept: "text/event-stream",
|
|
25
|
+
Authorization: `Bearer ${options.apiKey}`,
|
|
26
|
+
"User-Agent": `edena-cli/${VERSION}`,
|
|
27
|
+
...(lastId && { "Last-Event-ID": lastId }),
|
|
28
|
+
},
|
|
29
|
+
signal: options.signal,
|
|
30
|
+
});
|
|
31
|
+
if (!response.ok || !response.body) {
|
|
32
|
+
const body = (await response.json().catch(() => ({})));
|
|
33
|
+
const error = new ApiError(response.status, body.key ?? `http.${response.status}`, body.message ?? response.statusText, body.requestId ?? null, null);
|
|
34
|
+
if (response.status < 500 && response.status !== 429)
|
|
35
|
+
throw error;
|
|
36
|
+
throw Object.assign(error, { retryable: true });
|
|
37
|
+
}
|
|
38
|
+
options.onOpen?.(opened);
|
|
39
|
+
opened = true;
|
|
40
|
+
failures = 0;
|
|
41
|
+
let buffer = "";
|
|
42
|
+
let message = { id: null, event: "message", data: "" };
|
|
43
|
+
const decoder = new TextDecoder();
|
|
44
|
+
for await (const chunk of response.body) {
|
|
45
|
+
buffer += decoder.decode(chunk, { stream: true });
|
|
46
|
+
let newline;
|
|
47
|
+
while ((newline = buffer.indexOf("\n")) >= 0) {
|
|
48
|
+
const line = buffer.slice(0, newline).replace(/\r$/, "");
|
|
49
|
+
buffer = buffer.slice(newline + 1);
|
|
50
|
+
if (line === "") {
|
|
51
|
+
if (message.data !== "" || message.id) {
|
|
52
|
+
if (message.id)
|
|
53
|
+
lastId = message.id;
|
|
54
|
+
if (message.event !== "reconnect")
|
|
55
|
+
await options.onMessage(message);
|
|
56
|
+
}
|
|
57
|
+
message = { id: null, event: "message", data: "" };
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
if (line.startsWith(":"))
|
|
61
|
+
continue;
|
|
62
|
+
const colon = line.indexOf(":");
|
|
63
|
+
const field = colon < 0 ? line : line.slice(0, colon);
|
|
64
|
+
const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
|
|
65
|
+
if (field === "id")
|
|
66
|
+
message.id = value;
|
|
67
|
+
else if (field === "event")
|
|
68
|
+
message.event = value;
|
|
69
|
+
else if (field === "data")
|
|
70
|
+
message.data = message.data ? `${message.data}\n${value}` : value;
|
|
71
|
+
else if (field === "retry" && Number(value) > 0)
|
|
72
|
+
retryMs = Number(value);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
catch (error) {
|
|
77
|
+
if (options.signal.aborted)
|
|
78
|
+
return;
|
|
79
|
+
if (error instanceof ApiError && !error.retryable)
|
|
80
|
+
throw error;
|
|
81
|
+
failures++;
|
|
82
|
+
options.onDisconnect?.(error);
|
|
83
|
+
}
|
|
84
|
+
await sleep(Math.min(retryMs * 2 ** Math.max(0, failures - 1), 30_000), options.signal);
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
/** `15m`, `2h`, `1d` ago, or an ISO date, as an ISO date for `since`. */
|
|
88
|
+
export function sinceOf(value) {
|
|
89
|
+
const match = /^(\d+)\s*([smhd])$/.exec(value.trim());
|
|
90
|
+
if (match) {
|
|
91
|
+
const unit = { s: 1, m: 60, h: 3600, d: 86400 }[match[2]];
|
|
92
|
+
return new Date(Date.now() - Number(match[1]) * unit * 1000).toISOString();
|
|
93
|
+
}
|
|
94
|
+
const date = new Date(value);
|
|
95
|
+
if (Number.isNaN(date.getTime()))
|
|
96
|
+
throw new Error(`“${value}” is not a time: use 15m, 2h, 1d or an ISO date.`);
|
|
97
|
+
return date.toISOString();
|
|
98
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { dirname, join } from "node:path";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
/** The package's root: `dist/src/version.js` sits two folders below it. */
|
|
5
|
+
export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
|
|
6
|
+
/** The CLI's version, from its own package.json. */
|
|
7
|
+
export const VERSION = (() => {
|
|
8
|
+
try {
|
|
9
|
+
return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
|
|
10
|
+
}
|
|
11
|
+
catch {
|
|
12
|
+
return "0.0.0";
|
|
13
|
+
}
|
|
14
|
+
})();
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@edena-solutions/cli",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0-beta.0",
|
|
4
|
+
"description": "Edena's command line: every operation of the Edena API as a command, for people and for coding agents.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"homepage": "https://github.com/Edena-Solutions/edena-cli#readme",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/Edena-Solutions/edena-cli.git"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/Edena-Solutions/edena-cli/issues"
|
|
13
|
+
},
|
|
14
|
+
"type": "module",
|
|
15
|
+
"bin": {
|
|
16
|
+
"edena": "dist/src/cli.js"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"dist/src",
|
|
20
|
+
"skill",
|
|
21
|
+
"README.md",
|
|
22
|
+
"LICENSE"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=20"
|
|
26
|
+
},
|
|
27
|
+
"publishConfig": {
|
|
28
|
+
"access": "public"
|
|
29
|
+
},
|
|
30
|
+
"scripts": {
|
|
31
|
+
"build": "tsc -p tsconfig.json",
|
|
32
|
+
"test": "tsc -p tsconfig.json && node --test dist/test/*.test.js",
|
|
33
|
+
"prepublishOnly": "npm test"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@types/node": "^22.0.0",
|
|
37
|
+
"typescript": "^5.9.0"
|
|
38
|
+
},
|
|
39
|
+
"keywords": [
|
|
40
|
+
"edena",
|
|
41
|
+
"cli",
|
|
42
|
+
"api",
|
|
43
|
+
"schools",
|
|
44
|
+
"agent-skills"
|
|
45
|
+
]
|
|
46
|
+
}
|
package/skill/SKILL.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: edena
|
|
3
|
+
description: Work with Edena, the management platform for schools, nurseries and academies, through the `edena` CLI. Use it to look up or change an organization's students, families, staff, invoices, payments, attendance, timetables, communications and every other module, and to help integrate the Edena API into an app. Use when the user mentions Edena, asks about their school's or academy's data in any language, or wants to build against the Edena API.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Edena CLI
|
|
7
|
+
|
|
8
|
+
`edena` runs every operation of the Edena API as a command: `edena <category> <action>`, such as `edena students list` or `edena invoices get <id>`. Commands, help and output are in English; answer the user in their own language.
|
|
9
|
+
|
|
10
|
+
## 1. Check the session first
|
|
11
|
+
|
|
12
|
+
1. `edena --version`. If it is missing: `npm install -g @edena-solutions/cli` (needs Node.js 20 or later).
|
|
13
|
+
2. `edena whoami --json`. It answers the organization, its `environment` (`sandbox` or `live`) and the key's role.
|
|
14
|
+
3. If it says "Not signed in", run `edena login`. It prints a link and a code: tell the user to open the link, check the code and approve it in the Edena console, then wait for the command to finish. Do not try to sign in any other way.
|
|
15
|
+
4. Signed in to more than one organization: `edena profiles --json` lists them, `edena use <profile>` switches.
|
|
16
|
+
|
|
17
|
+
## 2. Find the command, never guess it
|
|
18
|
+
|
|
19
|
+
- `edena docs search "<english keywords>" --json` finds the operations that match, best first. Turn the user's request into English keywords: "alumnos sin pagador" → `"students payers"`, "facturas pendientes" → `"unpaid invoices"`.
|
|
20
|
+
- `edena <category> <action> --help` shows its arguments, flags, body fields and what it answers.
|
|
21
|
+
- `edena docs show <category> <action>` adds every type it uses, as TypeScript.
|
|
22
|
+
- `edena categories --json` lists every category; `edena <category>` lists its actions.
|
|
23
|
+
|
|
24
|
+
## 3. Run it
|
|
25
|
+
|
|
26
|
+
- Always add `--json` and read the result as JSON.
|
|
27
|
+
- Path parameters go in order after the action: `edena students get <id>`.
|
|
28
|
+
- Query parameters and body fields are flags: `--status active`, `--name "Ana"`. A whole body: `--data '<json>'`, `--data @file.json` or `--data -` from stdin.
|
|
29
|
+
- Lists come in pages: `--all` fetches every page; `--page` and `--pageSize` pick one.
|
|
30
|
+
- A file answer (a PDF, a spreadsheet) needs `--output <file>`.
|
|
31
|
+
- Anything the commands do not cover: `edena api GET /path --query name=value`.
|
|
32
|
+
|
|
33
|
+
## 4. Changing data needs the user's yes
|
|
34
|
+
|
|
35
|
+
- Every write (create, update, delete, send, cancel) needs `--yes`. Before you run one, tell the user exactly what will change, in which organization and environment (from `whoami`), and wait for an explicit yes.
|
|
36
|
+
- In `live` the data is real: say so, and that families or staff may be notified. Never write in `live` just to try something; use the sandbox.
|
|
37
|
+
- For several changes, show the full list first and confirm it once.
|
|
38
|
+
|
|
39
|
+
## 5. When something fails
|
|
40
|
+
|
|
41
|
+
Errors come as JSON on stderr: `{ "error": { "status", "key", "message", "requestId" } }`. Exit codes: 2 the command was called wrong (read the message and `--help`), 3 not signed in or the key's role does not reach it, 4 not found, 5 conflict, 6 rate limited (wait a little and retry). Decide on `key`, and give the user the `requestId` if they need Edena's help.
|
|
42
|
+
|
|
43
|
+
## 6. Integrating the Edena API into an app
|
|
44
|
+
|
|
45
|
+
1. Find the categories involved with `edena docs search`.
|
|
46
|
+
2. `edena prompt <category>` prints the full specification of a category: the API's rules, every operation and every type. Read it and follow it; do not invent endpoints or fields.
|
|
47
|
+
3. `edena types <category>... > src/edena.types.ts` writes the TypeScript types to the project.
|
|
48
|
+
4. The key lives in the `EDENA_API_KEY` environment variable, on the server only. An app acting for its users in the browser uses end-user tokens: `edena docs show end-user-tokens issue`.
|
|
49
|
+
5. Build and test against the sandbox. To follow changes without polling, use webhooks: `edena webhook-events types --json` lists every event.
|
|
50
|
+
|
|
51
|
+
## 7. Developing webhooks and watching the API
|
|
52
|
+
|
|
53
|
+
- `edena listen --forward-to http://localhost:<port>/<path>` forwards the organization's events, as they happen, to the user's local server, signed like real webhooks. It runs until stopped, so start it in the background or ask the user to run it in another terminal; `edena listen --print-secret` gives the secret their server verifies `Edena-Signature` with.
|
|
54
|
+
- `edena trigger <type>` resends the latest real event of a type to that server, to test a handler without changing data.
|
|
55
|
+
- `edena logs --mine --json` follows the requests made with this terminal's key, to see what an integration is calling and what the API answered.
|
|
56
|
+
- `edena open <section>` opens the developer console (keys, webhooks, requests, docs…) for the user.
|
|
57
|
+
|
|
58
|
+
## 8. Answering
|
|
59
|
+
|
|
60
|
+
Answer in the user's language. Summarise what the commands returned (counts, names, totals) instead of pasting JSON, unless they ask for it, and say which organization and environment the data comes from.
|