@authoric/js 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.
- package/LICENSE +21 -0
- package/README.md +94 -3
- package/bin/authoric.mjs +345 -0
- package/dist/cjs/app-actions.js +40 -0
- package/dist/cjs/app-actions.js.map +1 -0
- package/dist/cjs/auth.js +335 -0
- package/dist/cjs/auth.js.map +1 -0
- package/dist/cjs/client.js +121 -0
- package/dist/cjs/client.js.map +1 -0
- package/dist/cjs/cookies.js +137 -0
- package/dist/cjs/cookies.js.map +1 -0
- package/dist/cjs/data.js +197 -0
- package/dist/cjs/data.js.map +1 -0
- package/dist/cjs/errors.js +70 -0
- package/dist/cjs/errors.js.map +1 -0
- package/dist/cjs/files.js +188 -0
- package/dist/cjs/files.js.map +1 -0
- package/dist/cjs/generated/error-codes.js +435 -0
- package/dist/cjs/generated/error-codes.js.map +1 -0
- package/dist/cjs/index.js +31 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/realtime.js +191 -0
- package/dist/cjs/realtime.js.map +1 -0
- package/dist/cjs/routes.js +113 -0
- package/dist/cjs/routes.js.map +1 -0
- package/dist/cjs/session.js +430 -0
- package/dist/cjs/session.js.map +1 -0
- package/dist/cjs/storage-adapters.js +83 -0
- package/dist/cjs/storage-adapters.js.map +1 -0
- package/dist/cjs/teams.js +152 -0
- package/dist/cjs/teams.js.map +1 -0
- package/dist/cjs/transport.js +189 -0
- package/dist/cjs/transport.js.map +1 -0
- package/dist/cjs/types.js +7 -0
- package/dist/cjs/types.js.map +1 -0
- package/dist/esm/app-actions.d.ts +32 -0
- package/dist/esm/app-actions.d.ts.map +1 -0
- package/dist/esm/app-actions.js +37 -0
- package/dist/esm/app-actions.js.map +1 -0
- package/dist/esm/auth.d.ts +259 -0
- package/dist/esm/auth.d.ts.map +1 -0
- package/dist/esm/auth.js +331 -0
- package/dist/esm/auth.js.map +1 -0
- package/dist/esm/client.d.ts +82 -0
- package/dist/esm/client.d.ts.map +1 -0
- package/dist/esm/client.js +115 -0
- package/dist/esm/client.js.map +1 -0
- package/dist/esm/cookies.d.ts +66 -0
- package/dist/esm/cookies.d.ts.map +1 -0
- package/dist/esm/cookies.js +129 -0
- package/dist/esm/cookies.js.map +1 -0
- package/dist/esm/data.d.ts +211 -0
- package/dist/esm/data.d.ts.map +1 -0
- package/dist/esm/data.js +191 -0
- package/dist/esm/data.js.map +1 -0
- package/dist/esm/errors.d.ts +61 -0
- package/dist/esm/errors.d.ts.map +1 -0
- package/dist/esm/errors.js +63 -0
- package/dist/esm/errors.js.map +1 -0
- package/dist/esm/files.d.ts +76 -0
- package/dist/esm/files.d.ts.map +1 -0
- package/dist/esm/files.js +184 -0
- package/dist/esm/files.js.map +1 -0
- package/dist/esm/generated/error-codes.d.ts +5 -0
- package/dist/esm/generated/error-codes.d.ts.map +1 -0
- package/dist/esm/generated/error-codes.js +432 -0
- package/dist/esm/generated/error-codes.js.map +1 -0
- package/dist/esm/index.d.ts +22 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +9 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/realtime.d.ts +33 -0
- package/dist/esm/realtime.d.ts.map +1 -0
- package/dist/esm/realtime.js +186 -0
- package/dist/esm/realtime.js.map +1 -0
- package/dist/esm/routes.d.ts +75 -0
- package/dist/esm/routes.d.ts.map +1 -0
- package/dist/esm/routes.js +108 -0
- package/dist/esm/routes.js.map +1 -0
- package/dist/esm/session.d.ts +99 -0
- package/dist/esm/session.d.ts.map +1 -0
- package/dist/esm/session.js +425 -0
- package/dist/esm/session.js.map +1 -0
- package/dist/esm/storage-adapters.d.ts +31 -0
- package/dist/esm/storage-adapters.d.ts.map +1 -0
- package/dist/esm/storage-adapters.js +76 -0
- package/dist/esm/storage-adapters.js.map +1 -0
- package/dist/esm/teams.d.ts +157 -0
- package/dist/esm/teams.d.ts.map +1 -0
- package/dist/esm/teams.js +146 -0
- package/dist/esm/teams.js.map +1 -0
- package/dist/esm/transport.d.ts +56 -0
- package/dist/esm/transport.d.ts.map +1 -0
- package/dist/esm/transport.js +185 -0
- package/dist/esm/transport.js.map +1 -0
- package/dist/esm/types.d.ts +203 -0
- package/dist/esm/types.d.ts.map +1 -0
- package/dist/esm/types.js +6 -0
- package/dist/esm/types.js.map +1 -0
- package/package.json +54 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Authoric
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,94 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# @authoric/js
|
|
2
|
+
|
|
3
|
+
The client SDK for apps built on [Authoric](https://authoric.ai): sign-in and the user's own account,
|
|
4
|
+
data (queries, batches, realtime), files, teams, roles and billing, for your app's own users, from a
|
|
5
|
+
browser, React Native, or your server.
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install @authoric/js
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { createClient } from "@authoric/js";
|
|
13
|
+
|
|
14
|
+
const authoric = createClient({
|
|
15
|
+
url: "https://api.authoric.ai",
|
|
16
|
+
appUid: "0199a3c2-…", // your app's uid, from the console. Not a secret.
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
const result = await authoric.auth.signInWithPassword({ email, password });
|
|
20
|
+
if (result.mfa) {
|
|
21
|
+
// A second factor is owed: ask for the code, then
|
|
22
|
+
await authoric.auth.mfa.verify({ challengeId: result.mfa.challengeId, code });
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const { items } = await authoric.from("invoices").list({
|
|
26
|
+
where: { status: "open", total: { $gte: 100 } },
|
|
27
|
+
order: [{ column: "due_at", dir: "asc" }],
|
|
28
|
+
include: ["customer"],
|
|
29
|
+
limit: 25,
|
|
30
|
+
});
|
|
31
|
+
await authoric.from("invoices").updateMany([{ uid, values: { status: "paid" } }]);
|
|
32
|
+
const sub = authoric.from("invoices").subscribe((change) => console.log(change.op));
|
|
33
|
+
await authoric.storage.upload(storageUid, file, { path: "/2026/q3" });
|
|
34
|
+
|
|
35
|
+
await authoric.orgs.invitations.send({ inviteeEmail: "sam@example.com" });
|
|
36
|
+
const { products, publishableKey } = await authoric.billing.catalog();
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
On your own server, keep the session in a cookie on your domain, one client per request, and ask the
|
|
40
|
+
API who the user is:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { createServerClient } from "@authoric/js";
|
|
44
|
+
|
|
45
|
+
const authoric = createServerClient({ url, appUid, cookies: { get, set, remove } }); // this request's cookies
|
|
46
|
+
const me = await authoric.auth.getUser(); // verified by the API, never read from the cookie
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Everything is decided on the server: who may read or write which rows, which org a row belongs to,
|
|
50
|
+
which columns are redacted, which tables are locked. The SDK grants nothing and enforces nothing,
|
|
51
|
+
so anything it does, a plain HTTP call can do, and nothing it skips is unprotected.
|
|
52
|
+
|
|
53
|
+
## Typed tables
|
|
54
|
+
|
|
55
|
+
Generate types for your app's tables, then pass them to `createClient`:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
AUTHORIC_DEPLOY_KEY=… npx @authoric/js types --app <app uid> --url https://api.authoric.ai --out src/authoric-types.d.ts
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
import type { Database } from "./authoric-types";
|
|
63
|
+
const authoric = createClient<Database>({ url, appUid });
|
|
64
|
+
authoric.from("invoices"); // rows, inserts and updates typed by your schema
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The command needs a **deploy key** for the app (console › the app › Deployments › Deploy keys), the
|
|
68
|
+
same key CI deploys with. Never an end user's token. The file is types only, so nothing of it ships to
|
|
69
|
+
your users' browsers.
|
|
70
|
+
The app's **Deployments › Client types** in the console has a Download types button too.
|
|
71
|
+
|
|
72
|
+
## Security notes
|
|
73
|
+
|
|
74
|
+
- **The browser holds no secret.** `createClient` takes your API address and app uid, both public.
|
|
75
|
+
An agent API key (`plak_…`) is a full secret: the SDK refuses one outright, in every runtime.
|
|
76
|
+
- **Where the session is kept.** The access token lives in memory only. The refresh token goes to
|
|
77
|
+
the `storage` you choose: `localStorage` by default in a browser, so a reload keeps the user
|
|
78
|
+
signed in. `localStorage` is readable by any script on your page, as all browser storage is.
|
|
79
|
+
Refresh tokens are single-use, so when one is presented twice the session ends for every holder.
|
|
80
|
+
`storage: "session"`, `"memory"` or your own adapter (a native secure store, a server session)
|
|
81
|
+
keeps it elsewhere.
|
|
82
|
+
- **On a server, a cookie on your own domain.** `createServerClient` keeps the session (the access
|
|
83
|
+
token included, so a page load spends no refresh token) in a `Secure`, `SameSite=Lax` cookie, named
|
|
84
|
+
`__Host-…` where it can be, readable by default and `httpOnly` as an option. Create one client per
|
|
85
|
+
request, and trust `auth.getUser()`, never what the cookie says.
|
|
86
|
+
- **One refresh at a time, across tabs.** Tabs share one session and coordinate through Web Locks and
|
|
87
|
+
a BroadcastChannel, so several open tabs never look like token theft.
|
|
88
|
+
- **Errors are safe to log.** An `AuthoricError` carries the API's `status`, `code`, `message`,
|
|
89
|
+
`details` and `requestId`, never a token or a request body. The `debug` option logs route templates
|
|
90
|
+
and statuses only.
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
MIT
|
package/bin/authoric.mjs
ADDED
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// The `authoric` CLI, shipped with @authoric/js (notes/agent-ready-and-portable-plan.md A6).
|
|
3
|
+
//
|
|
4
|
+
// authoric init set up a project: authoric/authoric.json, AGENTS.md, .env entries, and the MCP
|
|
5
|
+
// config a coding agent connects with
|
|
6
|
+
// authoric pull the app's live definition, written into authoric/
|
|
7
|
+
// authoric plan what deploying authoric/ would change
|
|
8
|
+
// authoric deploy deploy authoric/ to the app, and wait for it to settle
|
|
9
|
+
// authoric promote deploy one app's definition to another (Sandbox to Live by deploy keys)
|
|
10
|
+
// authoric types write the app's TypeScript types for @authoric/js
|
|
11
|
+
//
|
|
12
|
+
// Coding agents connect over MCP (`authoric init` prints the config) and need none of the rest. These
|
|
13
|
+
// commands are for a definition kept in a repository, and use a DEPLOY KEY (console, the app,
|
|
14
|
+
// Deployments, Deploy keys): read from the environment only, never a flag, so it never lands in shell
|
|
15
|
+
// history; sent only to the address you name, never printed. There is no default address: a deploy
|
|
16
|
+
// key is never sent to a host you did not choose.
|
|
17
|
+
import { writeFileSync, mkdirSync, readFileSync, existsSync, readdirSync, statSync, appendFileSync } from "node:fs";
|
|
18
|
+
import { dirname, resolve, join, relative, sep } from "node:path";
|
|
19
|
+
|
|
20
|
+
const UID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
21
|
+
const BUNDLE_DIR = "authoric";
|
|
22
|
+
const TERMINAL = new Set(["live", "replaced", "failed", "rejected", "expired", "superseded", "canceled"]);
|
|
23
|
+
|
|
24
|
+
const usage = `Usage: authoric <command> [options]
|
|
25
|
+
|
|
26
|
+
init set up this project for Authoric (no key needed)
|
|
27
|
+
pull write the app's live definition into ./authoric
|
|
28
|
+
plan show what deploying ./authoric would change
|
|
29
|
+
deploy deploy ./authoric to the app and wait for it
|
|
30
|
+
promote deploy one app's definition to another: --to <app uid> (key: AUTHORIC_DEPLOY_KEY_TO)
|
|
31
|
+
types write the app's TypeScript types (--out authoric-types.d.ts)
|
|
32
|
+
|
|
33
|
+
Options:
|
|
34
|
+
--app the app's uid (or AUTHORIC_APP)
|
|
35
|
+
--url the API's address, such as https://api.authoric.ai (or AUTHORIC_API)
|
|
36
|
+
--out where \`types\` writes (default: authoric-types.d.ts)
|
|
37
|
+
--to the app \`promote\` deploys to
|
|
38
|
+
--json machine-readable output (plan, deploy, promote)
|
|
39
|
+
|
|
40
|
+
The deploy key is read from AUTHORIC_DEPLOY_KEY, never a flag.`;
|
|
41
|
+
|
|
42
|
+
const fail = (message, code = 1) => {
|
|
43
|
+
process.stderr.write(`authoric: ${message}\n`);
|
|
44
|
+
process.exit(code);
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
const parseArgs = (argv) => {
|
|
48
|
+
const [command, ...rest] = argv;
|
|
49
|
+
const options = {};
|
|
50
|
+
for (let i = 0; i < rest.length; i += 1) {
|
|
51
|
+
const arg = rest[i];
|
|
52
|
+
const [flag, inline] = arg.split("=", 2);
|
|
53
|
+
const value = inline ?? rest[i + 1];
|
|
54
|
+
const take = () => {
|
|
55
|
+
if (inline === undefined) i += 1;
|
|
56
|
+
if (value === undefined || value.startsWith("--")) fail(`${flag} needs a value\n\n${usage}`);
|
|
57
|
+
return value;
|
|
58
|
+
};
|
|
59
|
+
if (flag === "--app") options.app = take();
|
|
60
|
+
else if (flag === "--url") options.url = take();
|
|
61
|
+
else if (flag === "--out") options.out = take();
|
|
62
|
+
else if (flag === "--to") options.to = take();
|
|
63
|
+
else if (flag === "--json") options.json = true;
|
|
64
|
+
else if (flag === "--key" || flag === "--token") {
|
|
65
|
+
fail("the deploy key is read from AUTHORIC_DEPLOY_KEY only, never a flag (a flag lands in shell history).");
|
|
66
|
+
} else if (flag === "--help" || flag === "-h") {
|
|
67
|
+
process.stdout.write(`${usage}\n`);
|
|
68
|
+
process.exit(0);
|
|
69
|
+
} else fail(`unknown option ${flag}\n\n${usage}`);
|
|
70
|
+
}
|
|
71
|
+
return { command, options };
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const apiBase = (value) => {
|
|
75
|
+
let parsed;
|
|
76
|
+
try {
|
|
77
|
+
parsed = new URL(value);
|
|
78
|
+
} catch {
|
|
79
|
+
fail("--url must be the API's full address, such as https://api.authoric.ai");
|
|
80
|
+
}
|
|
81
|
+
const local = ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
|
|
82
|
+
if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
|
|
83
|
+
fail("--url must use https: a deploy key never travels in the clear.");
|
|
84
|
+
}
|
|
85
|
+
if (parsed.username || parsed.password || parsed.search || parsed.hash) {
|
|
86
|
+
fail("--url is the API's address alone, with no credentials, query or fragment.");
|
|
87
|
+
}
|
|
88
|
+
return `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
/** The app uid, the API address and the key a key-bearing command needs. */
|
|
92
|
+
const target = (options, { keyEnv = "AUTHORIC_DEPLOY_KEY", appOption = "app" } = {}) => {
|
|
93
|
+
const appUid = options[appOption] ?? (appOption === "app" ? process.env.AUTHORIC_APP : undefined);
|
|
94
|
+
if (!appUid || !UID.test(appUid)) fail(`--${appOption} must be the app's uid\n\n${usage}`);
|
|
95
|
+
const url = apiBase(options.url ?? process.env.AUTHORIC_API ?? fail(`--url is required (or set AUTHORIC_API)\n\n${usage}`));
|
|
96
|
+
const key = (process.env[keyEnv] || "").trim();
|
|
97
|
+
if (!key) fail(`set ${keyEnv} to a deploy key for the app (console, the app, Deployments, Deploy keys).`);
|
|
98
|
+
if (/^(au_agent_|plak_)/i.test(key)) fail("that is an agent API key, not a deploy key. Issue a deploy key for the app.");
|
|
99
|
+
if (/^au_approver_/i.test(key)) fail("that is an approver token, not a deploy key. Issue a deploy key for the app.");
|
|
100
|
+
return { appUid: appUid.toLowerCase(), url, key };
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/** POST one platform action with a deploy key; the parsed body, or a clear failure. */
|
|
104
|
+
const action = async ({ url, key }, name, body) => {
|
|
105
|
+
let response;
|
|
106
|
+
try {
|
|
107
|
+
response = await fetch(`${url}/platform/autocrud/apps/actions/${name}`, {
|
|
108
|
+
method: "POST",
|
|
109
|
+
headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json", Accept: "application/json" },
|
|
110
|
+
body: JSON.stringify(body),
|
|
111
|
+
redirect: "error",
|
|
112
|
+
});
|
|
113
|
+
} catch (error) {
|
|
114
|
+
fail(`could not reach ${url} (${error?.cause?.code || error?.message || "network error"})`);
|
|
115
|
+
}
|
|
116
|
+
let parsed = null;
|
|
117
|
+
try {
|
|
118
|
+
parsed = await response.json();
|
|
119
|
+
} catch {
|
|
120
|
+
// reported below
|
|
121
|
+
}
|
|
122
|
+
if (!response.ok) {
|
|
123
|
+
const inner = parsed?.error && typeof parsed.error === "object" ? parsed.error : parsed;
|
|
124
|
+
const code = inner?.code ? ` ${inner.code}` : "";
|
|
125
|
+
const message = inner?.error || inner?.message || "the request was refused";
|
|
126
|
+
fail(`${response.status}${code}: ${message}`);
|
|
127
|
+
}
|
|
128
|
+
return parsed;
|
|
129
|
+
};
|
|
130
|
+
|
|
131
|
+
// ---------------------------------------------------------------------------------------------
|
|
132
|
+
// the bundle on disk
|
|
133
|
+
// ---------------------------------------------------------------------------------------------
|
|
134
|
+
|
|
135
|
+
const bundleRoot = () => resolve(process.cwd(), BUNDLE_DIR);
|
|
136
|
+
|
|
137
|
+
const readBundle = () => {
|
|
138
|
+
const root = bundleRoot();
|
|
139
|
+
if (!existsSync(join(root, "authoric.json"))) fail(`no ${BUNDLE_DIR}/authoric.json here. Run \`authoric init\` or \`authoric pull\` first.`);
|
|
140
|
+
const files = [];
|
|
141
|
+
const walk = (dir) => {
|
|
142
|
+
for (const name of readdirSync(dir)) {
|
|
143
|
+
if (name === "node_modules" || name.startsWith(".")) continue;
|
|
144
|
+
const full = join(dir, name);
|
|
145
|
+
if (statSync(full).isDirectory()) walk(full);
|
|
146
|
+
else files.push({ path: relative(root, full).split(sep).join("/"), content: readFileSync(full, "utf8") });
|
|
147
|
+
}
|
|
148
|
+
};
|
|
149
|
+
walk(root);
|
|
150
|
+
return files;
|
|
151
|
+
};
|
|
152
|
+
|
|
153
|
+
const writeBundle = (files) => {
|
|
154
|
+
const root = bundleRoot();
|
|
155
|
+
for (const file of files) {
|
|
156
|
+
const out = resolve(root, file.path);
|
|
157
|
+
if (!out.startsWith(root)) fail(`refusing to write outside ${BUNDLE_DIR}/: ${file.path}`);
|
|
158
|
+
mkdirSync(dirname(out), { recursive: true });
|
|
159
|
+
writeFileSync(out, file.content);
|
|
160
|
+
}
|
|
161
|
+
return files.length;
|
|
162
|
+
};
|
|
163
|
+
|
|
164
|
+
const print = (options, human, machine) => {
|
|
165
|
+
if (options.json) process.stdout.write(`${JSON.stringify(machine, null, 2)}\n`);
|
|
166
|
+
else process.stdout.write(`${human}\n`);
|
|
167
|
+
};
|
|
168
|
+
|
|
169
|
+
const describePlan = (plan) => {
|
|
170
|
+
const lines = (plan.groups || plan.ops || []).flatMap((g) => g.lines || []).slice(0, 60);
|
|
171
|
+
const waits = plan.needs_approval?.length || 0;
|
|
172
|
+
return [
|
|
173
|
+
lines.length ? lines.map((l) => ` ${l}`).join("\n") : " Nothing changes.",
|
|
174
|
+
waits ? `\n${waits} change(s) wait for a person's approval (a removal, or a widening while the app is protected).` : "",
|
|
175
|
+
].join("");
|
|
176
|
+
};
|
|
177
|
+
|
|
178
|
+
const waitForDeployment = async (t, deploymentUid) => {
|
|
179
|
+
let deployment = null;
|
|
180
|
+
for (let i = 0; i < 120; i += 1) {
|
|
181
|
+
deployment = (await action(t, "deployment-get", { targetAppUid: t.appUid, deploymentUid }))?.deployment;
|
|
182
|
+
if (!deployment || TERMINAL.has(deployment.status) || deployment.status === "needs_approval") return deployment;
|
|
183
|
+
await new Promise((r) => setTimeout(r, 2000));
|
|
184
|
+
}
|
|
185
|
+
return deployment;
|
|
186
|
+
};
|
|
187
|
+
|
|
188
|
+
const reportDeployment = (options, t, deployment) => {
|
|
189
|
+
const status = deployment?.status || "unknown";
|
|
190
|
+
const where = `${t.url.replace(/\/\/api\./, "//console.")}/console/apps/${t.appUid}/deployments`;
|
|
191
|
+
const human =
|
|
192
|
+
status === "live"
|
|
193
|
+
? "authoric: deployed. It is live."
|
|
194
|
+
: status === "needs_approval"
|
|
195
|
+
? `authoric: the deployment waits for a person's approval (Deployments, in the console: ${where}). Nothing was skipped; it applies once approved.`
|
|
196
|
+
: `authoric: the deployment ended ${status}${deployment?.error ? `: ${deployment.error}` : ""}.`;
|
|
197
|
+
print(options, human, { status, deploymentUid: deployment?.uid || null });
|
|
198
|
+
// A wait for a person is its own exit code, so an agent or a pipeline can tell it from a failure.
|
|
199
|
+
if (status === "needs_approval") process.exit(3);
|
|
200
|
+
if (status !== "live") process.exit(1);
|
|
201
|
+
};
|
|
202
|
+
|
|
203
|
+
// ---------------------------------------------------------------------------------------------
|
|
204
|
+
// commands
|
|
205
|
+
// ---------------------------------------------------------------------------------------------
|
|
206
|
+
|
|
207
|
+
const AGENTS_MD = (appUid, url) => `# Built on Authoric
|
|
208
|
+
|
|
209
|
+
This project's backend is an Authoric app (a hosted backend: database, sign-in, organizations, storage,
|
|
210
|
+
handlers, jobs, email and governed agents).
|
|
211
|
+
|
|
212
|
+
- App uid: \`${appUid || "<your app uid>"}\` (not a secret; the frontend's only setting)
|
|
213
|
+
- API: \`${url || "https://api.authoric.ai"}\`
|
|
214
|
+
- Docs for agents: https://docs.authoric.ai/llms.txt (every page is also at its address plus \`.md\`)
|
|
215
|
+
|
|
216
|
+
## Working on the backend
|
|
217
|
+
|
|
218
|
+
Connect the Authoric MCP server (\`${url || "https://api.authoric.ai"}/mcp\`); signing in happens in the
|
|
219
|
+
browser. Then call \`authoricAppInfo\`, \`readBrief\`, and \`authoricGuide\` with topic \`start\`. Update the
|
|
220
|
+
brief (\`updateBrief\`) when you finish a piece of work.
|
|
221
|
+
|
|
222
|
+
Built in, never rebuilt: organizations (each customer business is one), users and sign-in, paid plans
|
|
223
|
+
(products). Rows are named by \`uid\`; references are \`<name>_uid\`.
|
|
224
|
+
|
|
225
|
+
When a tool returns \`pending_approval\`, it waits for a person: share the link it gives, then call
|
|
226
|
+
\`checkRun\`. Never retry it.
|
|
227
|
+
|
|
228
|
+
## Credentials
|
|
229
|
+
|
|
230
|
+
| Credential | Looks like | Where it lives |
|
|
231
|
+
|---|---|---|
|
|
232
|
+
| App uid | a uid | frontend code |
|
|
233
|
+
| Deploy key | \`au_deploy_…\` | \`AUTHORIC_DEPLOY_KEY\` in \`.env\` (gitignored) and CI secrets, never in code |
|
|
234
|
+
| Agent API key | \`au_agent_…\` | server environment only |
|
|
235
|
+
|
|
236
|
+
The frontend uses \`@authoric/js\` with \`createClient({ url, appUid })\` and never holds an \`au_\` key.
|
|
237
|
+
`;
|
|
238
|
+
|
|
239
|
+
const init = (options) => {
|
|
240
|
+
const appUid = options.app ?? process.env.AUTHORIC_APP ?? null;
|
|
241
|
+
if (appUid && !UID.test(appUid)) fail("--app must be the app's uid");
|
|
242
|
+
const url = options.url ? apiBase(options.url) : process.env.AUTHORIC_API ? apiBase(process.env.AUTHORIC_API) : null;
|
|
243
|
+
const root = bundleRoot();
|
|
244
|
+
const made = [];
|
|
245
|
+
if (!existsSync(join(root, "authoric.json"))) {
|
|
246
|
+
mkdirSync(root, { recursive: true });
|
|
247
|
+
writeFileSync(
|
|
248
|
+
join(root, "authoric.json"),
|
|
249
|
+
`${JSON.stringify({ $schema: "https://authoric.ai/schema/authoric-v1.json", formatVersion: 1, manage: ["handlers"], functionsRoot: "handlers" }, null, 2)}\n`,
|
|
250
|
+
);
|
|
251
|
+
made.push(`${BUNDLE_DIR}/authoric.json`);
|
|
252
|
+
}
|
|
253
|
+
const agentsFile = resolve(process.cwd(), "AGENTS.md");
|
|
254
|
+
if (!existsSync(agentsFile)) {
|
|
255
|
+
writeFileSync(agentsFile, AGENTS_MD(appUid, url));
|
|
256
|
+
made.push("AGENTS.md");
|
|
257
|
+
}
|
|
258
|
+
const envFile = resolve(process.cwd(), ".env");
|
|
259
|
+
const env = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
|
|
260
|
+
const lines = [
|
|
261
|
+
!/^AUTHORIC_API=/m.test(env) ? `AUTHORIC_API=${url || "https://api.authoric.ai"}` : null,
|
|
262
|
+
!/^AUTHORIC_APP=/m.test(env) ? `AUTHORIC_APP=${appUid || ""}` : null,
|
|
263
|
+
!/^AUTHORIC_DEPLOY_KEY=/m.test(env) ? "AUTHORIC_DEPLOY_KEY=" : null,
|
|
264
|
+
].filter(Boolean);
|
|
265
|
+
if (lines.length) {
|
|
266
|
+
appendFileSync(envFile, `${env && !env.endsWith("\n") ? "\n" : ""}${lines.join("\n")}\n`);
|
|
267
|
+
made.push(".env");
|
|
268
|
+
}
|
|
269
|
+
// .env holds a secret: make sure git never sees it.
|
|
270
|
+
const ignoreFile = resolve(process.cwd(), ".gitignore");
|
|
271
|
+
const ignore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
|
|
272
|
+
if (!/^\.env$/m.test(ignore)) {
|
|
273
|
+
appendFileSync(ignoreFile, `${ignore && !ignore.endsWith("\n") ? "\n" : ""}.env\n`);
|
|
274
|
+
made.push(".gitignore");
|
|
275
|
+
}
|
|
276
|
+
const mcp = `${url || "https://api.authoric.ai"}/mcp`;
|
|
277
|
+
process.stdout.write(
|
|
278
|
+
[
|
|
279
|
+
made.length ? `authoric: wrote ${made.join(", ")}` : "authoric: already set up",
|
|
280
|
+
"",
|
|
281
|
+
"Connect a coding agent (it signs in through your browser; there is no key to copy):",
|
|
282
|
+
` Claude Code: claude mcp add --transport http authoric ${mcp}`,
|
|
283
|
+
` Cursor: add an MCP server with the URL ${mcp}`,
|
|
284
|
+
"",
|
|
285
|
+
"For deploying from this repository, put a deploy key in .env as AUTHORIC_DEPLOY_KEY (console,",
|
|
286
|
+
"the app, Deployments, Deploy keys). It is gitignored.",
|
|
287
|
+
"",
|
|
288
|
+
].join("\n"),
|
|
289
|
+
);
|
|
290
|
+
};
|
|
291
|
+
|
|
292
|
+
const types = async (options) => {
|
|
293
|
+
const t = target(options);
|
|
294
|
+
const out = resolve(process.cwd(), options.out ?? "authoric-types.d.ts");
|
|
295
|
+
const body = await action(t, "app-types", { targetAppUid: t.appUid });
|
|
296
|
+
if (!body || typeof body.content !== "string") fail("the API answered without types.");
|
|
297
|
+
mkdirSync(dirname(out), { recursive: true });
|
|
298
|
+
writeFileSync(out, body.content, { mode: 0o644 });
|
|
299
|
+
process.stdout.write(`authoric: wrote ${body.tables ?? "the"} table types to ${out}\n`);
|
|
300
|
+
};
|
|
301
|
+
|
|
302
|
+
const pull = async (options) => {
|
|
303
|
+
const t = target(options);
|
|
304
|
+
const body = await action(t, "definition-export", { targetAppUid: t.appUid });
|
|
305
|
+
const n = writeBundle(body.files || []);
|
|
306
|
+
print(options, `authoric: wrote ${n} file(s) into ${BUNDLE_DIR}/`, { files: n });
|
|
307
|
+
};
|
|
308
|
+
|
|
309
|
+
const plan = async (options) => {
|
|
310
|
+
const t = target(options);
|
|
311
|
+
const body = await action(t, "definition-plan", { targetAppUid: t.appUid, source: "upload", files: readBundle() });
|
|
312
|
+
print(options, describePlan(body), { summary: body.summary, ops: body.ops, needsApproval: body.needs_approval, planHash: body.plan_hash });
|
|
313
|
+
};
|
|
314
|
+
|
|
315
|
+
const deploy = async (options) => {
|
|
316
|
+
const t = target(options);
|
|
317
|
+
const body = await action(t, "definition-deploy", { targetAppUid: t.appUid, source: "upload", files: readBundle() });
|
|
318
|
+
reportDeployment(options, t, await waitForDeployment(t, body.deployment?.uid));
|
|
319
|
+
};
|
|
320
|
+
|
|
321
|
+
const promote = async (options) => {
|
|
322
|
+
const from = target(options);
|
|
323
|
+
const to = target(options, { keyEnv: "AUTHORIC_DEPLOY_KEY_TO", appOption: "to" });
|
|
324
|
+
const exported = await action(from, "definition-export", { targetAppUid: from.appUid });
|
|
325
|
+
// A Builder is never promoted: agents stay in the app they were made for (A9.3).
|
|
326
|
+
const files = (exported.files || []).filter((f) => !f.path.startsWith("agents/"));
|
|
327
|
+
const body = await action(to, "definition-deploy", { targetAppUid: to.appUid, source: "upload", files });
|
|
328
|
+
reportDeployment(options, to, await waitForDeployment(to, body.deployment?.uid));
|
|
329
|
+
};
|
|
330
|
+
|
|
331
|
+
const COMMANDS = { init, types, pull, plan, deploy, promote };
|
|
332
|
+
|
|
333
|
+
const main = async () => {
|
|
334
|
+
const argv = process.argv.slice(2);
|
|
335
|
+
if (["--help", "-h", "help"].includes(argv[0]) || argv.includes("--help")) {
|
|
336
|
+
process.stdout.write(`${usage}\n`);
|
|
337
|
+
return;
|
|
338
|
+
}
|
|
339
|
+
const { command, options } = parseArgs(argv);
|
|
340
|
+
const run = COMMANDS[command];
|
|
341
|
+
if (!run) fail(command ? `unknown command "${command}"\n\n${usage}` : usage);
|
|
342
|
+
await run(options);
|
|
343
|
+
};
|
|
344
|
+
|
|
345
|
+
main().catch((error) => fail(error?.message || String(error)));
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
// Every seeded table ACTION the client SDK calls (teams, roles, billing), in ONE table.
|
|
3
|
+
//
|
|
4
|
+
// These are `table_meta.config.actions` descriptors seeded by the API's migration 001, served under
|
|
5
|
+
// `/autocrud/:table/actions/...`. The backend suite reads this file
|
|
6
|
+
// (api/tests/clientSdkActions.parity.test.js) and checks each entry against 001's descriptors, with
|
|
7
|
+
// the same method, so a renamed or withdrawn action fails there instead of in a customer's app.
|
|
8
|
+
// A `:name` segment is filled, URL-encoded, by the caller.
|
|
9
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
10
|
+
exports.APP_ACTIONS = void 0;
|
|
11
|
+
const action = (table, method, path) => Object.freeze({ table, method, path });
|
|
12
|
+
exports.APP_ACTIONS = Object.freeze({
|
|
13
|
+
// ── Teams ────────────────────────────────────────────────────────────────────────────────────
|
|
14
|
+
myOrgs: action("org_memberships", "GET", "/actions/my-orgs"),
|
|
15
|
+
members: action("org_memberships", "GET", "/actions"),
|
|
16
|
+
removeMember: action("org_memberships", "POST", "/actions/org-memberships/remove"),
|
|
17
|
+
leaveOrg: action("org_memberships", "POST", "/actions/org-memberships/leave"),
|
|
18
|
+
renameOrg: action("orgs", "POST", "/actions/rename-active"),
|
|
19
|
+
createOrg: action("orgs", "POST", "/actions/create"),
|
|
20
|
+
invite: action("org_invitations", "POST", "/actions/org-invites"),
|
|
21
|
+
invitesSent: action("org_invitations", "GET", "/actions/org-invites/sent"),
|
|
22
|
+
invitesReceived: action("org_invitations", "GET", "/actions/org-invites/received"),
|
|
23
|
+
inviteAccept: action("org_invitations", "POST", "/actions/org-invites/accept"),
|
|
24
|
+
inviteDeny: action("org_invitations", "POST", "/actions/org-invites/deny"),
|
|
25
|
+
inviteCancel: action("org_invitations", "POST", "/actions/org-invites/cancel"),
|
|
26
|
+
inviteRevoke: action("org_invitations", "POST", "/actions/org-invites/revoke"),
|
|
27
|
+
// ── Roles ────────────────────────────────────────────────────────────────────────────────────
|
|
28
|
+
userRoles: action("users", "GET", "/actions/:userUid/roles"),
|
|
29
|
+
bindRole: action("users", "POST", "/actions/bind-role"),
|
|
30
|
+
unbindRole: action("users", "POST", "/actions/unbind-role"),
|
|
31
|
+
// ── Billing ──────────────────────────────────────────────────────────────────────────────────
|
|
32
|
+
catalog: action("products", "GET", "/actions/catalog"),
|
|
33
|
+
subscribe: action("products", "POST", "/actions/subscribe"),
|
|
34
|
+
order: action("products", "POST", "/actions/order"),
|
|
35
|
+
subscriptions: action("user_subscriptions", "GET", "/actions/subscriptions"),
|
|
36
|
+
cancelSubscription: action("user_subscriptions", "POST", "/actions/:subscriptionUid/cancel"),
|
|
37
|
+
resumeSubscription: action("user_subscriptions", "POST", "/actions/:subscriptionUid/resume"),
|
|
38
|
+
entitlements: action("user_subscriptions", "GET", "/actions/entitlements"),
|
|
39
|
+
});
|
|
40
|
+
//# sourceMappingURL=app-actions.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app-actions.js","sourceRoot":"","sources":["../../src/app-actions.ts"],"names":[],"mappings":";AAAA,wFAAwF;AACxF,EAAE;AACF,oGAAoG;AACpG,oEAAoE;AACpE,oGAAoG;AACpG,gGAAgG;AAChG,2DAA2D;;;AAQ3D,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,MAA2B,EAAE,IAAY,EAAa,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAElH,QAAA,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,kBAAkB,CAAC;IAC5D,OAAO,EAAE,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,UAAU,CAAC;IACrD,YAAY,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,iCAAiC,CAAC;IAClF,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,gCAAgC,CAAC;IAC7E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,wBAAwB,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC;IACpD,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,sBAAsB,CAAC;IACjE,WAAW,EAAE,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,2BAA2B,CAAC;IAC1E,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,+BAA+B,CAAC;IAClF,YAAY,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,CAAC;IAC9E,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,2BAA2B,CAAC;IAC1E,YAAY,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,CAAC;IAC9E,YAAY,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,6BAA6B,CAAC;IAE9E,gGAAgG;IAChG,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,yBAAyB,CAAC;IAC5D,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,oBAAoB,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,sBAAsB,CAAC;IAE3D,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,kBAAkB,CAAC;IACtD,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,oBAAoB,CAAC;IAC3D,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,CAAC;IACnD,aAAa,EAAE,MAAM,CAAC,oBAAoB,EAAE,KAAK,EAAE,wBAAwB,CAAC;IAC5E,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,EAAE,kCAAkC,CAAC;IAC5F,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,EAAE,kCAAkC,CAAC;IAC5F,YAAY,EAAE,MAAM,CAAC,oBAAoB,EAAE,KAAK,EAAE,uBAAuB,CAAC;CAC1E,CAAC,CAAC"}
|