@votrix-ai/cli 0.0.0-stage → 0.2.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.
- package/README.md +192 -2
- package/SITE-TRACKING-CLI-DESIGN.md +117 -0
- package/dist/src/agent.js +366 -0
- package/dist/src/auth.js +283 -0
- package/dist/src/cli.js +170 -0
- package/dist/src/commands.js +116 -0
- package/dist/src/core.js +373 -0
- package/dist/src/integrations.js +156 -0
- package/dist/src/site.js +278 -0
- package/dist/src/tools.js +289 -0
- package/dist/src/zip.js +112 -0
- package/docs/API.md +98 -0
- package/docs/cli/account.md +77 -0
- package/docs/cli/agent.md +105 -0
- package/docs/cli/files.md +65 -0
- package/docs/cli/integrations.md +67 -0
- package/docs/cli/media.md +45 -0
- package/docs/cli/runs.md +44 -0
- package/docs/cli/scraper.md +45 -0
- package/docs/cli/seo.md +45 -0
- package/docs/cli/site.md +137 -0
- package/docs/cli/social.md +85 -0
- package/docs/cli/ui.md +45 -0
- package/package.json +30 -4
- package/production.json +5 -0
- package/skills/votrix/SKILL.md +97 -0
- package/skills/votrix/agents/openai.yaml +4 -0
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
// `votrix tools`: media, seo, scraper, ui (catalogs on the backend), social, site, files.
|
|
2
|
+
//
|
|
3
|
+
// What is inside a category (models, datasets, sources, recipes) is read from
|
|
4
|
+
// the backend every time, so a model swap needs no new CLI.
|
|
5
|
+
import { existsSync, readFileSync, statSync } from "node:fs";
|
|
6
|
+
import { downloadCards } from "./agent.js";
|
|
7
|
+
import { emit, note, sleep, usage, uuidOf, VotrixError } from "./core.js";
|
|
8
|
+
import { runSite } from "./site.js";
|
|
9
|
+
import { runIntegrations } from "./integrations.js";
|
|
10
|
+
import { categories as CATEGORIES } from "./commands.js";
|
|
11
|
+
const FIXED_FLAGS = new Set(["mode", "input", "max-credits", "max-cost", "out", "no-wait", "workspace", "json"]);
|
|
12
|
+
// What a caller pays is credits; the provider's dollar cost stays on the backend.
|
|
13
|
+
function inCredits(run) {
|
|
14
|
+
if (!run || typeof run !== "object")
|
|
15
|
+
return run;
|
|
16
|
+
const { estimate_usd, cost_usd, ...rest } = run;
|
|
17
|
+
return rest;
|
|
18
|
+
}
|
|
19
|
+
function exploreInCredits(detail) {
|
|
20
|
+
for (const mode of Object.values(detail?.modes ?? {})) {
|
|
21
|
+
if (mode && typeof mode === "object")
|
|
22
|
+
Reflect.deleteProperty(mode, "price");
|
|
23
|
+
}
|
|
24
|
+
return detail;
|
|
25
|
+
}
|
|
26
|
+
const WAIT_SECONDS = 25;
|
|
27
|
+
// `--some-param value` -> input.some_param; JSON values parse; a repeated flag is
|
|
28
|
+
// a list; a value that is a local file is uploaded and passed as asset:<id>.
|
|
29
|
+
async function inputOf(ctx) {
|
|
30
|
+
let input = {};
|
|
31
|
+
const given = ctx.flags.input;
|
|
32
|
+
if (given !== undefined) {
|
|
33
|
+
const text = String(given).startsWith("@") ? readFileSync(String(given).slice(1), "utf8") : String(given);
|
|
34
|
+
try {
|
|
35
|
+
input = JSON.parse(text);
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
throw usage("--input must be a JSON object, or @file.json.");
|
|
39
|
+
}
|
|
40
|
+
if (!input || typeof input !== "object" || Array.isArray(input))
|
|
41
|
+
throw usage("--input must be a JSON object.");
|
|
42
|
+
}
|
|
43
|
+
const parse = (value) => {
|
|
44
|
+
if (typeof value !== "string")
|
|
45
|
+
return value;
|
|
46
|
+
try {
|
|
47
|
+
return JSON.parse(value);
|
|
48
|
+
}
|
|
49
|
+
catch {
|
|
50
|
+
return value;
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
for (const [flag, value] of Object.entries(ctx.flags)) {
|
|
54
|
+
if (FIXED_FLAGS.has(flag))
|
|
55
|
+
continue;
|
|
56
|
+
input[flag.replace(/-/g, "_")] = Array.isArray(value) ? value.map(parse) : parse(value);
|
|
57
|
+
}
|
|
58
|
+
const workspace = await ctx.workspace();
|
|
59
|
+
const uploaded = new Map();
|
|
60
|
+
const upload = async (value) => {
|
|
61
|
+
if (typeof value === "string" && value.length < 1024 && !value.includes("://") && existsSync(value)
|
|
62
|
+
&& statSync(value).isFile()) {
|
|
63
|
+
if (!uploaded.has(value))
|
|
64
|
+
uploaded.set(value, `asset:${(await ctx.client.upload(value, workspace)).id}`);
|
|
65
|
+
return uploaded.get(value);
|
|
66
|
+
}
|
|
67
|
+
if (Array.isArray(value))
|
|
68
|
+
return Promise.all(value.map(upload));
|
|
69
|
+
if (value && typeof value === "object") {
|
|
70
|
+
return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([k, v]) => [k, await upload(v)])));
|
|
71
|
+
}
|
|
72
|
+
return value;
|
|
73
|
+
};
|
|
74
|
+
return upload(input);
|
|
75
|
+
}
|
|
76
|
+
async function finish(ctx, run) {
|
|
77
|
+
if (ctx.flags.out && run.files?.length) {
|
|
78
|
+
run.files = await downloadCards(ctx, run.files, ctx.flags.out);
|
|
79
|
+
}
|
|
80
|
+
emit(inCredits(run));
|
|
81
|
+
return run.status === "failed" ? 1 : 0;
|
|
82
|
+
}
|
|
83
|
+
async function waitFor(ctx, run) {
|
|
84
|
+
const workspace = await ctx.workspace();
|
|
85
|
+
const started = Date.now();
|
|
86
|
+
let last = 0;
|
|
87
|
+
while (run.status === "running") {
|
|
88
|
+
try {
|
|
89
|
+
run = await ctx.client.request("GET", `/tools/runs/${run.run_id}?wait=${WAIT_SECONDS}`, { workspace, timeoutMs: (WAIT_SECONDS + 15) * 1000 });
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
if (!(error instanceof VotrixError) || error.kind !== "network")
|
|
93
|
+
throw error;
|
|
94
|
+
await sleep(3000);
|
|
95
|
+
}
|
|
96
|
+
const minutes = Math.floor((Date.now() - started) / 60_000);
|
|
97
|
+
if (run.status === "running" && minutes > last) {
|
|
98
|
+
last = minutes;
|
|
99
|
+
note(`Still running (${minutes} min), still waiting. Stopping the wait does not stop the run: votrix tools runs get ${run.run_id} picks it up later.`);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return run;
|
|
103
|
+
}
|
|
104
|
+
async function runCategory(ctx, category, action) {
|
|
105
|
+
const workspace = await ctx.workspace();
|
|
106
|
+
const call = (method, path, body) => ctx.client.request(method, path, { workspace, body });
|
|
107
|
+
const name = ctx.positional[0];
|
|
108
|
+
if (action === "list")
|
|
109
|
+
return emit(await call("GET", `/tools/${category}`)), 0;
|
|
110
|
+
if (action === "explore") {
|
|
111
|
+
if (!name)
|
|
112
|
+
throw usage(`Usage: votrix tools ${category} explore <name> [--mode MODE]`);
|
|
113
|
+
const mode = ctx.flags.mode ? `?mode=${encodeURIComponent(ctx.flags.mode)}` : "";
|
|
114
|
+
return emit(exploreInCredits(await call("GET", `/tools/${category}/${encodeURIComponent(name)}${mode}`))), 0;
|
|
115
|
+
}
|
|
116
|
+
if (action === "run") {
|
|
117
|
+
if (!name)
|
|
118
|
+
throw usage(`Usage: votrix tools ${category} run <name> [--mode MODE] [--<parameter> VALUE ...] [--input JSON|@file] [--max-credits N] [--out DIR] [--no-wait]`);
|
|
119
|
+
const body = { input: await inputOf(ctx) };
|
|
120
|
+
if (ctx.flags.mode)
|
|
121
|
+
body.mode = ctx.flags.mode;
|
|
122
|
+
if (ctx.flags["max-credits"] !== undefined) {
|
|
123
|
+
const cap = Number(ctx.flags["max-credits"]);
|
|
124
|
+
if (!(cap > 0))
|
|
125
|
+
throw usage("--max-credits must be a positive number of credits, e.g. --max-credits 50.");
|
|
126
|
+
body.max_credits = cap;
|
|
127
|
+
}
|
|
128
|
+
// Still accepted from 0.2.0 scripts: a cap in USD of provider cost.
|
|
129
|
+
if (ctx.flags["max-cost"] !== undefined)
|
|
130
|
+
body.max_cost_usd = Number(ctx.flags["max-cost"]);
|
|
131
|
+
let run = await call("POST", `/tools/${category}/${encodeURIComponent(name)}/runs`, body);
|
|
132
|
+
const estimate = run.estimate_credits != null ? ` · estimate ≈ ${run.estimate_credits} credits` : "";
|
|
133
|
+
note(`Started ${category} ${run.name}${run.mode ? ` ${run.mode}` : ""} · run ${run.run_id}${estimate}`);
|
|
134
|
+
if (ctx.flags["no-wait"])
|
|
135
|
+
return emit(inCredits(run)), 0;
|
|
136
|
+
return finish(ctx, await waitFor(ctx, run));
|
|
137
|
+
}
|
|
138
|
+
throw usage(`Unknown command 'votrix tools ${category} ${action ?? ""}'.`, "Run votrix tools --help.");
|
|
139
|
+
}
|
|
140
|
+
async function runRuns(ctx, action) {
|
|
141
|
+
const workspace = await ctx.workspace();
|
|
142
|
+
if (action === "list") {
|
|
143
|
+
const query = new URLSearchParams({ limit: String(ctx.flags.limit ?? 20) });
|
|
144
|
+
if (ctx.flags.category)
|
|
145
|
+
query.set("category", ctx.flags.category);
|
|
146
|
+
const listed = await ctx.client.request("GET", `/tools/runs?${query}`, { workspace });
|
|
147
|
+
return emit({ ...listed, runs: (listed?.runs ?? []).map(inCredits) }), 0;
|
|
148
|
+
}
|
|
149
|
+
const id = uuidOf(ctx.positional[0]);
|
|
150
|
+
if (!id)
|
|
151
|
+
throw usage("A run id is required.");
|
|
152
|
+
if (action === "get") {
|
|
153
|
+
const run = await ctx.client.request("GET", `/tools/runs/${id}`, { workspace });
|
|
154
|
+
return finish(ctx, ctx.flags["no-wait"] ? run : await waitFor(ctx, run));
|
|
155
|
+
}
|
|
156
|
+
if (action === "stop")
|
|
157
|
+
return emit(inCredits(await ctx.client.request("DELETE", `/tools/runs/${id}`, { workspace }))), 0;
|
|
158
|
+
throw usage(`Unknown command 'votrix tools runs ${action ?? ""}'.`, "Run votrix tools --help.");
|
|
159
|
+
}
|
|
160
|
+
// --- social -------------------------------------------------------------------
|
|
161
|
+
async function runSocial(ctx, action, sub) {
|
|
162
|
+
const workspace = await ctx.workspace();
|
|
163
|
+
const base = "/tools/social";
|
|
164
|
+
const call = (method, path, body) => ctx.client.request(method, base + path, { workspace, body, timeoutMs: 360_000 });
|
|
165
|
+
if (action === "accounts") {
|
|
166
|
+
const accounts = (await call("GET", "/accounts")).accounts ?? [];
|
|
167
|
+
const platform = ctx.flags.platform;
|
|
168
|
+
return emit({ accounts: platform ? accounts.filter((a) => a.platform === platform) : accounts }), 0;
|
|
169
|
+
}
|
|
170
|
+
if (action !== "posts")
|
|
171
|
+
throw usage(`Unknown command 'votrix tools social ${action ?? ""}'.`, "Run votrix tools --help.");
|
|
172
|
+
const id = ctx.positional[0];
|
|
173
|
+
const needId = () => { if (!id)
|
|
174
|
+
throw usage("A post id is required."); return encodeURIComponent(id); };
|
|
175
|
+
if (sub === "list") {
|
|
176
|
+
const query = new URLSearchParams({ limit: String(ctx.flags.limit ?? 50), offset: String(ctx.flags.offset ?? 0) });
|
|
177
|
+
for (const a of [].concat(ctx.flags.account ?? []))
|
|
178
|
+
query.append("account_id", a);
|
|
179
|
+
for (const s of [].concat(ctx.flags.status ?? []))
|
|
180
|
+
query.append("status", s);
|
|
181
|
+
return emit(await call("GET", `/posts?${query}`)), 0;
|
|
182
|
+
}
|
|
183
|
+
if (sub === "get")
|
|
184
|
+
return emit(await call("GET", `/posts/${needId()}`)), 0;
|
|
185
|
+
if (sub === "results")
|
|
186
|
+
return emit(await call("GET", `/posts/${needId()}/results`)), 0;
|
|
187
|
+
if (sub === "cancel")
|
|
188
|
+
return emit(await call("DELETE", `/posts/${needId()}`)), 0;
|
|
189
|
+
if (sub === "create" || sub === "update") {
|
|
190
|
+
let body;
|
|
191
|
+
if (ctx.flags.file) {
|
|
192
|
+
const text = ctx.flags.file === "-" ? await import("./core.js").then((m) => m.readStdin()) : readFileSync(ctx.flags.file, "utf8");
|
|
193
|
+
body = JSON.parse(text);
|
|
194
|
+
}
|
|
195
|
+
else {
|
|
196
|
+
const accounts = [].concat(ctx.flags.account ?? []);
|
|
197
|
+
if (!accounts.length)
|
|
198
|
+
throw usage("--account is required (see votrix tools social accounts).");
|
|
199
|
+
const media = [];
|
|
200
|
+
for (const item of [].concat(ctx.flags.media ?? [])) {
|
|
201
|
+
if (/^https?:\/\//.test(item))
|
|
202
|
+
media.push({ url: item });
|
|
203
|
+
else if (uuidOf(item) && !existsSync(item))
|
|
204
|
+
media.push({ asset_id: uuidOf(item) });
|
|
205
|
+
else
|
|
206
|
+
media.push({ asset_id: (await ctx.client.upload(item, workspace)).id });
|
|
207
|
+
}
|
|
208
|
+
if (ctx.flags["thumbnail"] && media.length === 1) {
|
|
209
|
+
const thumb = ctx.flags.thumbnail;
|
|
210
|
+
Object.assign(media[0], uuidOf(thumb) ? { thumbnail_asset_id: uuidOf(thumb) }
|
|
211
|
+
: /^https?:/.test(thumb) ? { thumbnail_url: thumb } : { thumbnail_asset_id: (await ctx.client.upload(thumb, workspace)).id });
|
|
212
|
+
}
|
|
213
|
+
const caption = ctx.flags["caption-file"] ? readFileSync(ctx.flags["caption-file"], "utf8") : ctx.flags.caption ?? "";
|
|
214
|
+
body = { account_ids: accounts, caption, media, draft: Boolean(ctx.flags.draft) };
|
|
215
|
+
if (ctx.flags["schedule-at"])
|
|
216
|
+
body.scheduled_at = ctx.flags["schedule-at"];
|
|
217
|
+
if (ctx.flags.title)
|
|
218
|
+
body.platform_configurations = { youtube: { title: ctx.flags.title } };
|
|
219
|
+
}
|
|
220
|
+
return emit(sub === "create" ? await call("POST", "/posts", body) : await call("PUT", `/posts/${needId()}`, body)), 0;
|
|
221
|
+
}
|
|
222
|
+
throw usage(`Unknown command 'votrix tools social posts ${sub ?? ""}'.`, "Run votrix tools --help.");
|
|
223
|
+
}
|
|
224
|
+
// --- files --------------------------------------------------------------------
|
|
225
|
+
async function runFiles(ctx, action) {
|
|
226
|
+
const workspace = await ctx.workspace();
|
|
227
|
+
if (action === "upload") {
|
|
228
|
+
if (!ctx.positional.length)
|
|
229
|
+
throw usage("Usage: votrix tools files upload PATH [PATH ...]");
|
|
230
|
+
const uploaded = [];
|
|
231
|
+
for (const path of ctx.positional)
|
|
232
|
+
uploaded.push(await ctx.client.upload(path, workspace));
|
|
233
|
+
return emit({ files: uploaded, public: false,
|
|
234
|
+
note: "Private to this workspace. votrix tools files publish <asset> --name N gives a permanent public URL." }), 0;
|
|
235
|
+
}
|
|
236
|
+
if (action === "get") {
|
|
237
|
+
const id = uuidOf(ctx.positional[0]);
|
|
238
|
+
if (!id)
|
|
239
|
+
throw usage("An asset id is required.");
|
|
240
|
+
return emit(await ctx.client.request("GET", `/files/${id}`, { workspace })), 0;
|
|
241
|
+
}
|
|
242
|
+
if (action === "pull") {
|
|
243
|
+
const cards = [];
|
|
244
|
+
for (const given of ctx.positional) {
|
|
245
|
+
const id = uuidOf(given);
|
|
246
|
+
if (!id)
|
|
247
|
+
throw usage(`'${given}' is not an asset id.`);
|
|
248
|
+
const row = await ctx.client.request("GET", `/files/${id}`, { workspace });
|
|
249
|
+
cards.push({ asset_id: id, filename: row.filename });
|
|
250
|
+
}
|
|
251
|
+
return emit({ files: await downloadCards(ctx, cards, ctx.flags.out ?? ".") }), 0;
|
|
252
|
+
}
|
|
253
|
+
if (action === "publish") {
|
|
254
|
+
const given = ctx.positional[0];
|
|
255
|
+
if (!given || !ctx.flags.name)
|
|
256
|
+
throw usage("Usage: votrix tools files publish <asset>|PATH --name <name.ext>");
|
|
257
|
+
// A local file is uploaded first; publishing is what makes it public.
|
|
258
|
+
const id = uuidOf(given) ?? (existsSync(given) ? (await ctx.client.upload(given, workspace)).id : undefined);
|
|
259
|
+
if (!id)
|
|
260
|
+
throw usage(`'${given}' is neither an asset id nor a file.`);
|
|
261
|
+
return emit(await ctx.client.request("POST", `/files/${id}/publish`, { workspace, body: { name: ctx.flags.name } })), 0;
|
|
262
|
+
}
|
|
263
|
+
if (action === "library") {
|
|
264
|
+
const query = new URLSearchParams({ limit: String(ctx.flags.limit ?? 50) });
|
|
265
|
+
if (ctx.flags.query)
|
|
266
|
+
query.set("q", ctx.flags.query);
|
|
267
|
+
for (const g of [].concat(ctx.flags["mime-group"] ?? []))
|
|
268
|
+
query.append("mime_group", g);
|
|
269
|
+
if (ctx.flags.before)
|
|
270
|
+
query.set("before", ctx.flags.before);
|
|
271
|
+
return emit(await ctx.client.request("GET", `/files/save/list?${query}`, { workspace })), 0;
|
|
272
|
+
}
|
|
273
|
+
throw usage(`Unknown command 'votrix tools files ${action ?? ""}'.`, "Run votrix tools --help.");
|
|
274
|
+
}
|
|
275
|
+
export async function runTools(ctx, group, action, sub) {
|
|
276
|
+
if (CATEGORIES.includes(group))
|
|
277
|
+
return runCategory(ctx, group, action);
|
|
278
|
+
if (group === "runs")
|
|
279
|
+
return runRuns(ctx, action);
|
|
280
|
+
if (group === "social")
|
|
281
|
+
return runSocial(ctx, action, sub);
|
|
282
|
+
if (group === "files")
|
|
283
|
+
return runFiles(ctx, action);
|
|
284
|
+
if (group === "site")
|
|
285
|
+
return runSite(ctx, action, sub);
|
|
286
|
+
if (group === "integrations")
|
|
287
|
+
return runIntegrations(ctx, action);
|
|
288
|
+
throw usage(`Unknown tools group '${group ?? ""}'.`, "Run votrix tools --help.");
|
|
289
|
+
}
|
package/dist/src/zip.js
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// Plain zip files without dependencies: pack a folder (deflate), and unpack the
|
|
2
|
+
// website / video project archives employees hand over.
|
|
3
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { dirname, relative, resolve, sep } from "node:path";
|
|
5
|
+
import { deflateRawSync, inflateRawSync } from "node:zlib";
|
|
6
|
+
import { VotrixError } from "./core.js";
|
|
7
|
+
const CRC_TABLE = (() => {
|
|
8
|
+
const table = new Uint32Array(256);
|
|
9
|
+
for (let n = 0; n < 256; n++) {
|
|
10
|
+
let c = n;
|
|
11
|
+
for (let k = 0; k < 8; k++)
|
|
12
|
+
c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
|
|
13
|
+
table[n] = c >>> 0;
|
|
14
|
+
}
|
|
15
|
+
return table;
|
|
16
|
+
})();
|
|
17
|
+
function crc32(data) {
|
|
18
|
+
let c = 0xffffffff;
|
|
19
|
+
for (let i = 0; i < data.length; i++)
|
|
20
|
+
c = CRC_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
|
|
21
|
+
return (c ^ 0xffffffff) >>> 0;
|
|
22
|
+
}
|
|
23
|
+
// A plain zip (deflate), paths relative to `root` with forward slashes.
|
|
24
|
+
export function zipFolder(root, files) {
|
|
25
|
+
const locals = [];
|
|
26
|
+
const centrals = [];
|
|
27
|
+
let offset = 0;
|
|
28
|
+
for (const path of files) {
|
|
29
|
+
const name = Buffer.from(relative(root, path).split(sep).join("/"), "utf8");
|
|
30
|
+
const data = readFileSync(path);
|
|
31
|
+
const packed = deflateRawSync(data);
|
|
32
|
+
const crc = crc32(data);
|
|
33
|
+
const local = Buffer.alloc(30);
|
|
34
|
+
local.writeUInt32LE(0x04034b50, 0);
|
|
35
|
+
local.writeUInt16LE(20, 4);
|
|
36
|
+
local.writeUInt16LE(0x0800, 6);
|
|
37
|
+
local.writeUInt16LE(8, 8);
|
|
38
|
+
local.writeUInt32LE(0, 10);
|
|
39
|
+
local.writeUInt32LE(crc, 14);
|
|
40
|
+
local.writeUInt32LE(packed.length, 18);
|
|
41
|
+
local.writeUInt32LE(data.length, 22);
|
|
42
|
+
local.writeUInt16LE(name.length, 26);
|
|
43
|
+
local.writeUInt16LE(0, 28);
|
|
44
|
+
const central = Buffer.alloc(46);
|
|
45
|
+
central.writeUInt32LE(0x02014b50, 0);
|
|
46
|
+
central.writeUInt16LE(20, 4);
|
|
47
|
+
central.writeUInt16LE(20, 6);
|
|
48
|
+
central.writeUInt16LE(0x0800, 8);
|
|
49
|
+
central.writeUInt16LE(8, 10);
|
|
50
|
+
central.writeUInt32LE(0, 12);
|
|
51
|
+
central.writeUInt32LE(crc, 16);
|
|
52
|
+
central.writeUInt32LE(packed.length, 20);
|
|
53
|
+
central.writeUInt32LE(data.length, 24);
|
|
54
|
+
central.writeUInt16LE(name.length, 28);
|
|
55
|
+
central.writeUInt32LE(offset, 42);
|
|
56
|
+
locals.push(local, name, packed);
|
|
57
|
+
centrals.push(central, name);
|
|
58
|
+
offset += local.length + name.length + packed.length;
|
|
59
|
+
}
|
|
60
|
+
const centralSize = centrals.reduce((n, b) => n + b.length, 0);
|
|
61
|
+
const end = Buffer.alloc(22);
|
|
62
|
+
end.writeUInt32LE(0x06054b50, 0);
|
|
63
|
+
end.writeUInt16LE(files.length, 8);
|
|
64
|
+
end.writeUInt16LE(files.length, 10);
|
|
65
|
+
end.writeUInt32LE(centralSize, 12);
|
|
66
|
+
end.writeUInt32LE(offset, 16);
|
|
67
|
+
return Buffer.concat([...locals, ...centrals, end]);
|
|
68
|
+
}
|
|
69
|
+
// Unpack `zipPath` into `dir`; -> the number of files written. Entries that would
|
|
70
|
+
// land outside `dir` (absolute, or with ..) are refused.
|
|
71
|
+
export function unzipTo(zipPath, dir) {
|
|
72
|
+
const data = readFileSync(zipPath);
|
|
73
|
+
let end = -1;
|
|
74
|
+
for (let i = data.length - 22; i >= Math.max(0, data.length - 65_557); i--) {
|
|
75
|
+
if (data.readUInt32LE(i) === 0x06054b50) {
|
|
76
|
+
end = i;
|
|
77
|
+
break;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
if (end < 0)
|
|
81
|
+
throw new VotrixError("server", "The project archive is not a zip file.");
|
|
82
|
+
const count = data.readUInt16LE(end + 10);
|
|
83
|
+
let at = data.readUInt32LE(end + 16);
|
|
84
|
+
const root = resolve(dir);
|
|
85
|
+
let written = 0;
|
|
86
|
+
for (let n = 0; n < count; n++) {
|
|
87
|
+
if (data.readUInt32LE(at) !== 0x02014b50)
|
|
88
|
+
throw new VotrixError("server", "The project archive is damaged.");
|
|
89
|
+
const method = data.readUInt16LE(at + 10);
|
|
90
|
+
const size = data.readUInt32LE(at + 20);
|
|
91
|
+
const nameLength = data.readUInt16LE(at + 28);
|
|
92
|
+
const extra = data.readUInt16LE(at + 30);
|
|
93
|
+
const comment = data.readUInt16LE(at + 32);
|
|
94
|
+
const local = data.readUInt32LE(at + 42);
|
|
95
|
+
const name = data.toString("utf8", at + 46, at + 46 + nameLength);
|
|
96
|
+
at += 46 + nameLength + extra + comment;
|
|
97
|
+
if (name.endsWith("/"))
|
|
98
|
+
continue;
|
|
99
|
+
const target = resolve(root, name);
|
|
100
|
+
if (!target.startsWith(root + sep))
|
|
101
|
+
throw new VotrixError("server", `The project archive has an unsafe path: ${name}`);
|
|
102
|
+
const start = local + 30 + data.readUInt16LE(local + 26) + data.readUInt16LE(local + 28);
|
|
103
|
+
const raw = data.subarray(start, start + size);
|
|
104
|
+
const body = method === 0 ? raw : method === 8 ? inflateRawSync(raw) : null;
|
|
105
|
+
if (!body)
|
|
106
|
+
throw new VotrixError("server", `Cannot unpack ${name} (compression ${method}).`);
|
|
107
|
+
mkdirSync(dirname(target), { recursive: true });
|
|
108
|
+
writeFileSync(target, body);
|
|
109
|
+
written++;
|
|
110
|
+
}
|
|
111
|
+
return written;
|
|
112
|
+
}
|
package/docs/API.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Votrix AI CLI HTTP API
|
|
2
|
+
|
|
3
|
+
Use the backend origin selected by the CLI. Send `Authorization: Bearer <credential>` and `X-Workspace-Id: <workspace UUID>` on workspace requests. A workspace API key acts within its own grant. Site operations require `tools:sites` and integrations require `tools:integrations`. Send JSON request bodies with `Content-Type: application/json`.
|
|
4
|
+
|
|
5
|
+
## Website analytics
|
|
6
|
+
|
|
7
|
+
Deploy with `POST /tools/sites/{site}/versions` and a workspace ZIP asset ID. Tracking defaults to enabled. A track toggle takes `{"enabled":true}` or `{"enabled":false}` and returns the tracking state and whether the site changed.
|
|
8
|
+
|
|
9
|
+
Query `POST /tools/sites/{site}/track/events` with `{"period":"30d","by":"source","event":"visit"}`. Available results contain `rows` with a grouping value, distinct browser count (`visitors`), and event count (`count`).
|
|
10
|
+
|
|
11
|
+
Query `POST /tools/sites/{site}/track/funnel` with the following body. The period defaults to 30 days and the conversion window to seven days. A grouped response contains `groups`. An ungrouped response contains `steps`, each with a name, visitor count and conversion percentages.
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{"steps":["visit","login","signup_completed"],"where":{"source":["utm:instagram"]},"period":"30d","window":"7d"}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
See [site tracking](../SITE-TRACKING-CLI-DESIGN.md) for supported values and example responses.
|
|
18
|
+
|
|
19
|
+
## Connected applications
|
|
20
|
+
|
|
21
|
+
List workspace connections with `GET /tools/integrations`. To connect an app, post `{"app":"gmail"}` to `/tools/integrations/connect` and give the hosted URL to the user. Search for actions with `{"query":"read my Gmail profile","toolkits":["gmail"]}`. Fetch an action schema, then post `{"arguments":{}}` to its validate or execute endpoint. Select an account with the optional `account` ID. Execution returns `ok` plus `data` or an error. A completed HTTP request can still return `ok: false`. See [connected apps](cli/integrations.md).
|
|
22
|
+
|
|
23
|
+
## Endpoint reference
|
|
24
|
+
|
|
25
|
+
Path placeholders appear in braces. Required body fields end with an asterisk. Query parameters are optional unless marked. Where a request uses SSE, the response is an event stream. For signed file uploads, request a ticket, PUT the file bytes to its URL and then register the object. CLI login opens a sign-in with a PKCE challenge (`POST /cli/logins`), the user approves it for one workspace in the Votrix App, and the CLI exchanges the one-time code with its verifier for that workspace's key (`POST /cli/logins/exchange`). The earlier loopback sign-in (Google via Supabase PKCE, then a key per workspace) remains available.
|
|
26
|
+
|
|
27
|
+
### Account, sessions and files
|
|
28
|
+
|
|
29
|
+
| Method and path | Operation | Query parameters | JSON input fields |
|
|
30
|
+
| --- | --- | --- | --- |
|
|
31
|
+
| `POST /cli/logins` | Start CLI Sign-in (no credential) | — | `code_challenge*`, `device_id*`, `device_name` |
|
|
32
|
+
| `POST /cli/logins/{login_id}/approve` | Approve in the App (signed-in user) | — | `workspace_id*` |
|
|
33
|
+
| `POST /cli/logins/exchange` | Exchange Code for a Key (no credential) | — | `code*`, `code_verifier*` |
|
|
34
|
+
| `GET /employees` | List Employees | — | — |
|
|
35
|
+
| `POST /employees` | Hire Employee | — | `agent_blueprint_id*` |
|
|
36
|
+
| `POST /sessions/create` | Create Session Endpoint | — | `is_main`, `employee_id*`, `model`, `initial_message` |
|
|
37
|
+
| `GET /sessions/list` | List Sessions | `employee_id`, `limit`, `before` | — |
|
|
38
|
+
| `GET /sessions/{session_id}/status` | Get Session Status | — | — |
|
|
39
|
+
| `GET /sessions/{session_id}/events/list` | List Session Events | `before`, `after`, `limit` | — |
|
|
40
|
+
| `POST /sessions/{session_id}/events/send` | Send Session Event | — | JSON object |
|
|
41
|
+
| `GET /sessions/{session_id}/events/stream` | Stream Session Events | `after_seq` | — |
|
|
42
|
+
| `GET /sessions/{session_id}/files/list` | List Session Assets | — | — |
|
|
43
|
+
| `GET /workspaces` | List Workspaces | — | — |
|
|
44
|
+
| `POST /workspaces` | Create Workspace | — | `display_name*` |
|
|
45
|
+
| `POST /workspaces/{workspace_id}/api-keys` | Create Api Key | — | `name*`, `kind`, `scopes`, `device_id`, `expires_in_days` |
|
|
46
|
+
| `GET /workspaces/{workspace_id}/api-keys` | List Api Keys | — | — |
|
|
47
|
+
| `GET /users/me` | Get Me | — | — |
|
|
48
|
+
| `PATCH /users/me` | Update Me | — | `display_name*` |
|
|
49
|
+
| `GET /api-keys/current` | Current Api Key | — | — |
|
|
50
|
+
| `DELETE /api-keys/current` | Revoke Current Api Key | — | — |
|
|
51
|
+
| `GET /billing/balance` | Read Balance | — | — |
|
|
52
|
+
| `POST /files/upload-url` | Create Upload Url | — | `filename`, `mime_type`, `size_bytes` |
|
|
53
|
+
| `POST /files/register` | Register Upload | — | `storage_key*`, `filename`, `mime_type` |
|
|
54
|
+
| `GET /files/save/list` | List Library | `mime_group`, `employee_id`, `q`, `limit`, `before` | — |
|
|
55
|
+
| `GET /files/{file_id}` | Get File | — | — |
|
|
56
|
+
| `DELETE /files/{file_id}` | Delete File | — | — |
|
|
57
|
+
| `GET /files/{file_id}/download` | Download File | — | — |
|
|
58
|
+
| `POST /files/{file_id}/publish` | Publish File | — | `name*` |
|
|
59
|
+
|
|
60
|
+
### Tools
|
|
61
|
+
|
|
62
|
+
| Method and path | Operation | Query parameters | JSON input fields |
|
|
63
|
+
| --- | --- | --- | --- |
|
|
64
|
+
| `GET /tools/social/accounts` | Accounts | — | — |
|
|
65
|
+
| `POST /tools/social/posts` | Create Post | — | `account_ids*`, `caption`, `media`, `scheduled_at`, `draft`, `platform_configurations`, `account_configurations` |
|
|
66
|
+
| `GET /tools/social/posts` | List Posts | `account_id`, `status`, `limit`, `offset` | — |
|
|
67
|
+
| `GET /tools/social/posts/{post_id}` | Get Post | — | — |
|
|
68
|
+
| `PUT /tools/social/posts/{post_id}` | Update Post | — | `account_ids*`, `caption`, `media`, `scheduled_at`, `draft`, `platform_configurations`, `account_configurations` |
|
|
69
|
+
| `DELETE /tools/social/posts/{post_id}` | Cancel Post | — | — |
|
|
70
|
+
| `GET /tools/social/posts/{post_id}/results` | Post Results | `limit`, `offset` | — |
|
|
71
|
+
| `GET /tools/sites` | List Sites | — | — |
|
|
72
|
+
| `POST /tools/sites/{site}/versions` | Deploy | — | `asset_id*`, `address`, `track` |
|
|
73
|
+
| `GET /tools/sites/{site}/versions` | Versions | — | — |
|
|
74
|
+
| `GET /tools/sites/{site}/status` | Status | `version`, `logs` | — |
|
|
75
|
+
| `POST /tools/sites/{site}/live` | Put Back | — | `version*` |
|
|
76
|
+
| `GET /tools/sites/{site}/env` | Env List | — | — |
|
|
77
|
+
| `PUT /tools/sites/{site}/env` | Env Set | — | `variables*`, `target` |
|
|
78
|
+
| `POST /tools/sites/{site}/domains` | Domain Add | — | `domain*` |
|
|
79
|
+
| `GET /tools/sites/{site}/domains/{domain}` | Domain Status | — | — |
|
|
80
|
+
| `POST /tools/sites/{site}/track` | Set Tracking | — | `enabled*` |
|
|
81
|
+
| `POST /tools/sites/{site}/track/events` | Track Events | — | `period`, `by`, `event`, `where`, `search`, `limit` |
|
|
82
|
+
| `POST /tools/sites/{site}/track/funnel` | Track Funnel | — | `steps*`, `period`, `window`, `where`, `by` |
|
|
83
|
+
| `GET /tools/integrations` | Connections | `toolkit` | — |
|
|
84
|
+
| `POST /tools/integrations/connect` | Connect | — | `app*` |
|
|
85
|
+
| `POST /tools/integrations/search` | Search | — | `query*`, `toolkits`, `limit` |
|
|
86
|
+
| `GET /tools/integrations/actions/{action}/schema` | Schema | — | — |
|
|
87
|
+
| `POST /tools/integrations/actions/{action}/validate` | Validate | — | `arguments`, `account` |
|
|
88
|
+
| `POST /tools/integrations/actions/{action}/execute` | Execute | — | `arguments`, `account` |
|
|
89
|
+
| `GET /tools/runs` | List Runs | `category`, `limit` | — |
|
|
90
|
+
| `GET /tools/runs/{run_id}` | Get Run | `wait` | — |
|
|
91
|
+
| `DELETE /tools/runs/{run_id}` | Cancel Run | — | — |
|
|
92
|
+
| `GET /tools/{category}` | Catalog | — | — |
|
|
93
|
+
| `GET /tools/{category}/{name}` | Explore | `mode` | — |
|
|
94
|
+
| `POST /tools/{category}/{name}/runs` | Create Run | — | `mode`, `input`, `max_credits`, `max_cost_usd` |
|
|
95
|
+
|
|
96
|
+
## Errors
|
|
97
|
+
|
|
98
|
+
The HTTP status distinguishes invalid input, missing credentials, insufficient scope, missing resources and conflicts. Site and integration routes can provide structured `detail.type`, `detail.message`, and a suggested `detail.fix`. A POST to an execute endpoint can change provider data. After a timeout, inspect the provider before retrying.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Account and workspace
|
|
2
|
+
|
|
3
|
+
Select the workspace used for subsequent requests. Login stores one device key per workspace.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
### `votrix login`
|
|
8
|
+
|
|
9
|
+
Sign in with Google in a browser on this computer (default port 8765, timeout 180 seconds); saves a key for each of your workspaces. On a server or remote machine, create a CLI key for a workspace in the Votrix App and save it with --key.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
votrix login [--no-browser] [--port N] [--timeout S]
|
|
13
|
+
votrix login --key vtx_...
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Returns The account and its workspaces, or the workspace of the saved key.
|
|
17
|
+
|
|
18
|
+
### `votrix logout`
|
|
19
|
+
|
|
20
|
+
Revoke the saved device keys.
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
votrix logout
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Returns Logout result.
|
|
27
|
+
|
|
28
|
+
### `votrix whoami`
|
|
29
|
+
|
|
30
|
+
Show the current identity and workspace.
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
votrix whoami
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Returns Account and credential metadata; with several workspaces and none chosen, the workspaces and how to choose one.
|
|
37
|
+
|
|
38
|
+
### `votrix workspaces`
|
|
39
|
+
|
|
40
|
+
List available workspaces.
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
votrix workspaces
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Returns workspaces array.
|
|
47
|
+
|
|
48
|
+
### `votrix workspace use`
|
|
49
|
+
|
|
50
|
+
Select a workspace by ID.
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
votrix workspace use ID
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Returns workspace_id.
|
|
57
|
+
|
|
58
|
+
### `votrix credits`
|
|
59
|
+
|
|
60
|
+
Check workspace credit usage.
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
votrix credits
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Returns balance and recent charges.
|
|
67
|
+
|
|
68
|
+
## Example
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
votrix workspaces
|
|
72
|
+
votrix workspace use WORKSPACE_ID
|
|
73
|
+
votrix whoami
|
|
74
|
+
votrix credits
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Workspace selection returns workspace_id. Credits returns the balance and recent ledger entries.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Employees and sessions
|
|
2
|
+
|
|
3
|
+
Start a task with an employee slug or ID. Use a session ID to resume or inspect prior work.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
### `votrix agent ls`
|
|
8
|
+
|
|
9
|
+
List available employees.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
votrix agent ls
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Returns Employee identifiers and roles.
|
|
16
|
+
|
|
17
|
+
### `votrix agent ask`
|
|
18
|
+
|
|
19
|
+
Send a task and wait by default.
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
votrix agent ask EMPLOYEE TASK|- [--file PATH|ID ...] [--session ID] [--out DIR] [--no-wait]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Returns Session ID and, after completion, reply and presented files.
|
|
26
|
+
|
|
27
|
+
### `votrix agent wait`
|
|
28
|
+
|
|
29
|
+
Wait for the latest task.
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
votrix agent wait SESSION [--out DIR]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Returns Session status, reply and presented files.
|
|
36
|
+
|
|
37
|
+
### `votrix agent sessions`
|
|
38
|
+
|
|
39
|
+
List recent conversations.
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
votrix agent sessions [--employee NAME] [--limit N] [--before UPDATED_AT]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Returns Session records.
|
|
46
|
+
|
|
47
|
+
### `votrix agent get`
|
|
48
|
+
|
|
49
|
+
Inspect a session without waiting.
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
votrix agent get SESSION
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Returns Session status.
|
|
56
|
+
|
|
57
|
+
### `votrix agent files`
|
|
58
|
+
|
|
59
|
+
List output files.
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
votrix agent files SESSION
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Returns File metadata.
|
|
66
|
+
|
|
67
|
+
### `votrix agent pull`
|
|
68
|
+
|
|
69
|
+
Download output assets.
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
votrix agent pull ASSET ... [--out DIR]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Returns Downloaded files and paths.
|
|
76
|
+
|
|
77
|
+
### `votrix agent history`
|
|
78
|
+
|
|
79
|
+
Read messages and presented files.
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
votrix agent history SESSION [--limit N] [--before SEQ]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Returns History rows and pagination.
|
|
86
|
+
|
|
87
|
+
### `votrix agent stop`
|
|
88
|
+
|
|
89
|
+
Interrupt a running session.
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
votrix agent stop SESSION
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Returns Session and interruption result.
|
|
96
|
+
|
|
97
|
+
## Example
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
votrix agent ls
|
|
101
|
+
votrix agent ask rebecca "Review the attached brief" --file brief.pdf --no-wait
|
|
102
|
+
votrix agent wait SESSION_ID --out ./results
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
A completed task returns session_id, status, reply and presented files.
|