The best way to control Claude Code, Codex and more from any computer or phone

main
ts 318 lines 10.7 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { RuntimeContext } from "alchemy/RuntimeContext";
3 import * as Data from "effect/Data";
4 import * as Effect from "effect/Effect";
5 import type * as Artifacts from "./Namespace.ts";
6
7 /**
8 * Bind a Cloudflare Artifacts namespace ({@link Namespace}) to a Worker and
9 * obtain the Effect-native {@link ReadWriteNamespaceClient} (read + write:
10 * create / list / get / delete / import). Repos looked up with `get` carry
11 * the full {@link RepoClient}: history and file reads plus token and fork
12 * management.
13 *
14 * ### Creating repos and tokens
15 * **Example:** Create a repo inside a Worker
16 * ```typescript
17 * const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
18 * const repo = yield* artifacts.create("starter-repo", {
19 * setDefaultBranch: "main",
20 * });
21 * ```
22 *
23 * **Example:** Mint a short-lived read token for an existing repo
24 * ```typescript
25 * const repo = yield* artifacts.get("starter-repo");
26 * const token = yield* repo.createToken("read", 3600);
27 * ```
28 *
29 * ### Reading history and files
30 * **Example:** List the latest commits on a branch
31 * ```typescript
32 * const repo = yield* artifacts.get("starter-repo");
33 * const commits = yield* repo.log({ ref: "main", limit: 10 });
34 * // [{ hash, treeHash, message, author, committer, parents, authoredAt, committedAt }]
35 * ```
36 *
37 * **Example:** Read a file at a ref
38 * ```typescript
39 * const file = yield* repo.readFile({ ref: "main", path: "README.md" });
40 * if (file !== null) {
41 * const text = yield* Effect.promise(() => file.text());
42 * }
43 * ```
44 *
45 * **Example:** Walk a commit's tree
46 * ```typescript
47 * const commit = yield* repo.readCommit(hash);
48 * const entries = commit ? yield* repo.readTree(commit.treeHash) : null;
49 * const blob = entries?.find((e) => e.name === "data.json");
50 * const bytes = blob ? yield* repo.readBlob(blob.hash) : null;
51 * ```
52 *
53 * ### Handling errors
54 * **Example:** Branch on the platform error code
55 * ```typescript
56 * const repo = yield* artifacts.get(name).pipe(
57 * Effect.catchTag("ArtifactsError", (e) =>
58 * e.code === "NOT_FOUND" ? Effect.succeed(undefined) : Effect.fail(e),
59 * ),
60 * );
61 * ```
62 *
63 * @binding
64 * @product Artifacts
65 * @category Developer Platform
66 */
67 export interface ReadWriteNamespace extends Binding.Service<
68 ReadWriteNamespace,
69 "Cloudflare.Artifacts.ReadWriteNamespace",
70 (namespace: Artifacts.Namespace) => Effect.Effect<ReadWriteNamespaceClient>
71 > {}
72
73 export const ReadWriteNamespace = Binding.Service<ReadWriteNamespace>(
74 "Cloudflare.Artifacts.ReadWriteNamespace",
75 );
76
77 /**
78 * Error codes the Artifacts binding attaches to a thrown error as `.code`.
79 * See the {@link https://developers.cloudflare.com/artifacts/api/errors/ | Artifacts errors reference}.
80 */
81 export type ArtifactsErrorCode = globalThis.ArtifactsErrorCode;
82
83 /**
84 * Failure of an Artifacts binding call. `code` and `numericCode` carry the
85 * platform's error code when the binding attached one, so callers can tell a
86 * missing repo (`NOT_FOUND`) or a repo that is still importing
87 * (`IMPORT_IN_PROGRESS`) from an outage (`INTERNAL_ERROR`). Both are
88 * `undefined` when the failure carried no code (e.g. a dropped RPC
89 * connection).
90 */
91 export class ArtifactsError extends Data.TaggedError("ArtifactsError")<{
92 message: string;
93 /** Platform error code, when the binding attached one. */
94 code?: ArtifactsErrorCode;
95 /** Numeric code matching the REST API's `errors[].code`, when attached. */
96 numericCode?: number;
97 cause: Error;
98 }> {}
99
100 export type Scope = "read" | "write";
101
102 export type CreateOptions = {
103 readOnly?: boolean;
104 description?: string;
105 setDefaultBranch?: string;
106 };
107
108 export type ImportOptions = {
109 source: { url: string; branch?: string; depth?: number };
110 target: {
111 name: string;
112 opts?: { description?: string; readOnly?: boolean };
113 };
114 };
115
116 export type ListOptions = {
117 limit?: number;
118 cursor?: string;
119 };
120
121 export type ForkOptions = {
122 description?: string;
123 readOnly?: boolean;
124 defaultBranchOnly?: boolean;
125 };
126
127 export type LogOptions = {
128 /**
129 * Branch, tag, or commit ID to walk from.
130 * @default "HEAD"
131 */
132 ref?: string;
133 /**
134 * Maximum number of commits to return (capped at 1000 by the platform).
135 * @default 50
136 */
137 limit?: number;
138 /**
139 * Number of matching commits to skip.
140 * @default 0
141 */
142 offset?: number;
143 };
144
145 export type ReadFileOptions = {
146 /** Branch, tag, or commit ID to resolve. */
147 ref: string;
148 /** Non-empty repository-relative path. */
149 path: string;
150 };
151
152 /**
153 * Classification of a Git tree entry, derived from its mode: `tree` is a
154 * directory, `blob` a regular file, `symlink` a symbolic link, `gitlink` a
155 * submodule reference, and `exec` an executable file.
156 */
157 export type TreeEntryType = ArtifactsTreeEntryType;
158
159 /** An immediate child of a Git tree, as returned by `readTree`. */
160 export type TreeEntry = ArtifactsTreeEntry;
161
162 /** An author or committer identity on a commit. */
163 export type CommitIdentity = ArtifactsCommitMetadata["author"];
164
165 /** Decoded commit metadata, as returned by `log` and `readCommit`. */
166 export type CommitMetadata = ArtifactsCommitMetadata;
167
168 /**
169 * The runtime repo capability returned by the binding's `get(name)`: an RPC
170 * stub whose metadata comes from `info()` rather than from properties.
171 */
172 export type RepoHandle = ArtifactsRepo;
173
174 /**
175 * Read surface of a single Artifacts repo: metadata, token listing, commit
176 * history, and Git object / file reads. Handed out by
177 * {@link ReadNamespaceClient.get}.
178 */
179 export interface ReadRepoClient {
180 /** Underlying Cloudflare runtime handle. */
181 raw: RepoHandle;
182 /** Current repo metadata. Each call performs a fresh lookup. */
183 info(): Effect.Effect<ArtifactsRepoInfo, ArtifactsError, RuntimeContext>;
184 /** Token metadata for this repo (no plaintext). */
185 listTokens(): Effect.Effect<ArtifactsTokenListResult, ArtifactsError, RuntimeContext>;
186 /**
187 * Commits along the first-parent chain from `ref`, newest first. Empty when
188 * the ref cannot be resolved.
189 */
190 log(opts?: LogOptions): Effect.Effect<CommitMetadata[], ArtifactsError, RuntimeContext>;
191 /** Decode a commit by hash; `null` when the object is missing. */
192 readCommit(hash: string): Effect.Effect<CommitMetadata | null, ArtifactsError, RuntimeContext>;
193 /** Immediate children of a tree by hash; `null` when the object is missing. */
194 readTree(hash: string): Effect.Effect<TreeEntry[] | null, ArtifactsError, RuntimeContext>;
195 /**
196 * Raw bytes of a blob by hash (untyped `Blob`); `null` when the object is
197 * missing or is not a blob.
198 */
199 readBlob(hash: string): Effect.Effect<Blob | null, ArtifactsError, RuntimeContext>;
200 /**
201 * A file resolved from a branch, tag, or commit ID, as a MIME-typed `Blob`;
202 * `null` when the ref or path does not resolve to a file.
203 */
204 readFile(args: ReadFileOptions): Effect.Effect<Blob | null, ArtifactsError, RuntimeContext>;
205 }
206
207 /**
208 * Write surface of a single Artifacts repo: minting and revoking tokens, and
209 * forking.
210 */
211 export interface WriteRepoClient {
212 /** Underlying Cloudflare runtime handle. */
213 raw: RepoHandle;
214 createToken(
215 scope?: Scope,
216 ttl?: number,
217 ): Effect.Effect<ArtifactsCreateTokenResult, ArtifactsError, RuntimeContext>;
218 revokeToken(tokenOrId: string): Effect.Effect<boolean, ArtifactsError, RuntimeContext>;
219 fork(
220 name: string,
221 opts?: ForkOptions,
222 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError, RuntimeContext>;
223 }
224
225 /**
226 * Effect-native handle to a single Artifacts repo with read and write access.
227 * Wraps the runtime {@link RepoHandle} so each method returns an Effect.
228 */
229 export interface RepoClient extends ReadRepoClient, WriteRepoClient {}
230
231 /**
232 * Read-only client surface for an Artifacts namespace binding (look up + list).
233 */
234 export interface ReadNamespaceClient {
235 /** Effect resolving to the raw Cloudflare runtime binding. */
236 raw: Effect.Effect<Artifacts, never, RuntimeContext>;
237 /**
238 * Look up an existing repo by name. Fails with an `ArtifactsError` whose
239 * `code` is `NOT_FOUND` when the repo does not exist, or
240 * `CREATE_IN_PROGRESS` / `IMPORT_IN_PROGRESS` / `FORK_IN_PROGRESS` while it
241 * is not ready yet.
242 */
243 get(name: string): Effect.Effect<ReadRepoClient, ArtifactsError, RuntimeContext>;
244 list(opts?: ListOptions): Effect.Effect<ArtifactsRepoListResult, ArtifactsError, RuntimeContext>;
245 }
246
247 /**
248 * Write client surface for an Artifacts namespace binding (create / delete / import).
249 */
250 export interface WriteNamespaceClient {
251 /** Effect resolving to the raw Cloudflare runtime binding. */
252 raw: Effect.Effect<Artifacts, never, RuntimeContext>;
253 create(
254 name: string,
255 opts?: CreateOptions,
256 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError, RuntimeContext>;
257 delete(name: string): Effect.Effect<boolean, ArtifactsError, RuntimeContext>;
258 import(
259 opts: ImportOptions,
260 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError, RuntimeContext>;
261 }
262
263 /**
264 * Full read + write client for a Cloudflare Artifacts namespace binding.
265 */
266 export interface ReadWriteNamespaceClient extends ReadNamespaceClient, WriteNamespaceClient {
267 /**
268 * Look up an existing repo by name, with read and write access. Fails with
269 * an `ArtifactsError` whose `code` is `NOT_FOUND` when the repo does not
270 * exist.
271 */
272 get(name: string): Effect.Effect<RepoClient, ArtifactsError, RuntimeContext>;
273 }
274
275 /**
276 * Bind a Cloudflare Artifacts namespace with read-only access
277 * (`Cloudflare.Artifacts.ReadNamespace(Repos)`): `get` / `list` / `raw`. Repos
278 * returned by `get` expose the {@link ReadRepoClient} surface — metadata,
279 * commit history, and file reads.
280 *
281 * ### Reading history
282 * **Example:** Read a file at an older commit
283 * ```typescript
284 * const artifacts = yield* Cloudflare.Artifacts.ReadNamespace(Repos);
285 * const repo = yield* artifacts.get("starter-repo");
286 * const [, previous] = yield* repo.log({ ref: "main", limit: 2 });
287 * const file = previous
288 * ? yield* repo.readFile({ ref: previous.hash, path: "data.json" })
289 * : null;
290 * ```
291 *
292 * @binding
293 * @product Artifacts
294 * @category Developer Platform
295 */
296 export interface ReadNamespace extends Binding.Service<
297 ReadNamespace,
298 "Cloudflare.Artifacts.ReadNamespace",
299 (namespace: Artifacts.Namespace) => Effect.Effect<ReadNamespaceClient>
300 > {}
301 export const ReadNamespace = Binding.Service<ReadNamespace>("Cloudflare.Artifacts.ReadNamespace");
302
303 /**
304 * Bind a Cloudflare Artifacts namespace with write access
305 * (`Cloudflare.Artifacts.WriteNamespace(Repos)`): `create` / `delete` / `import`.
306 *
307 * @binding
308 * @product Artifacts
309 * @category Developer Platform
310 */
311 export interface WriteNamespace extends Binding.Service<
312 WriteNamespace,
313 "Cloudflare.Artifacts.WriteNamespace",
314 (namespace: Artifacts.Namespace) => Effect.Effect<WriteNamespaceClient>
315 > {}
316 export const WriteNamespace = Binding.Service<WriteNamespace>(
317 "Cloudflare.Artifacts.WriteNamespace",
318 );