1import * as Data from "effect/Data";
2import * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { RuntimeContext } from "../../RuntimeContext.ts";
5import 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).
11 *
12 * **Example:** Using Artifacts inside a Worker
13 * ```typescript
14 * const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
15 * const repo = yield* artifacts.create("starter-repo", {
16 * setDefaultBranch: "main",
17 * });
18 * ```
19 *
20 * @binding
21 * @product Artifacts
22 * @category Developer Platform
23 */
24export interface ReadWriteNamespace extends Binding.Service<
25 ReadWriteNamespace,
26 "Cloudflare.Artifacts.ReadWriteNamespace",
27 (namespace: Artifacts.Namespace) => Effect.Effect<ReadWriteNamespaceClient>
28> {}
29
30export const ReadWriteNamespace = Binding.Service<ReadWriteNamespace>(
31 "Cloudflare.Artifacts.ReadWriteNamespace",
32);
33
34export class ArtifactsError extends Data.TaggedError("ArtifactsError")<{
35 message: string;
36 cause: Error;
37}> {}
38
39export type Scope = "read" | "write";
40
41export type CreateOptions = {
42 readOnly?: boolean;
43 description?: string;
44 setDefaultBranch?: string;
45};
46
47export type ImportOptions = {
48 source: { url: string; branch?: string; depth?: number };
49 target: {
50 name: string;
51 opts?: { description?: string; readOnly?: boolean };
52 };
53};
54
55export type ListOptions = {
56 limit?: number;
57 cursor?: string;
58};
59
60export type ForkOptions = {
61 description?: string;
62 readOnly?: boolean;
63 defaultBranchOnly?: boolean;
64};
65
66/**
67 * Effect-native handle to a single Artifacts repo. Wraps the runtime
68 * {@link ArtifactsRepo} so each method returns an Effect.
69 */
70export interface RepoClient {
71 /** Underlying Cloudflare runtime handle. */
72 raw: ArtifactsRepo;
73 createToken(
74 scope?: Scope,
75 ttl?: number,
76 ): Effect.Effect<ArtifactsCreateTokenResult, ArtifactsError>;
77 listTokens(): Effect.Effect<ArtifactsTokenListResult, ArtifactsError>;
78 revokeToken(tokenOrId: string): Effect.Effect<boolean, ArtifactsError>;
79 fork(
80 name: string,
81 opts?: ForkOptions,
82 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError>;
83}
84
85/**
86 * Read-only client surface for an Artifacts namespace binding (look up + list).
87 */
88export interface ReadNamespaceClient {
89 /** Effect resolving to the raw Cloudflare runtime binding. */
90 raw: Effect.Effect<Artifacts, never, RuntimeContext>;
91 /** Look up an existing repo by name. Fails with `ArtifactsError` if missing. */
92 get(name: string): Effect.Effect<RepoClient, ArtifactsError, RuntimeContext>;
93 list(
94 opts?: ListOptions,
95 ): Effect.Effect<ArtifactsRepoListResult, ArtifactsError, RuntimeContext>;
96}
97
98/**
99 * Write client surface for an Artifacts namespace binding (create / delete / import).
100 */
101export interface WriteNamespaceClient {
102 /** Effect resolving to the raw Cloudflare runtime binding. */
103 raw: Effect.Effect<Artifacts, never, RuntimeContext>;
104 create(
105 name: string,
106 opts?: CreateOptions,
107 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError, RuntimeContext>;
108 delete(name: string): Effect.Effect<boolean, ArtifactsError, RuntimeContext>;
109 import(
110 opts: ImportOptions,
111 ): Effect.Effect<ArtifactsCreateRepoResult, ArtifactsError, RuntimeContext>;
112}
113
114/**
115 * Full read + write client for a Cloudflare Artifacts namespace binding.
116 */
117export interface ReadWriteNamespaceClient
118 extends ReadNamespaceClient, WriteNamespaceClient {}
119
120/**
121 * Bind a Cloudflare Artifacts namespace with read-only access
122 * (`Cloudflare.Artifacts.ReadNamespace(Repos)`): `get` / `list` / `raw`.
123 *
124 * @binding
125 * @product Artifacts
126 * @category Developer Platform
127 */
128export interface ReadNamespace extends Binding.Service<
129 ReadNamespace,
130 "Cloudflare.Artifacts.ReadNamespace",
131 (namespace: Artifacts.Namespace) => Effect.Effect<ReadNamespaceClient>
132> {}
133export const ReadNamespace = Binding.Service<ReadNamespace>(
134 "Cloudflare.Artifacts.ReadNamespace",
135);
136
137/**
138 * Bind a Cloudflare Artifacts namespace with write access
139 * (`Cloudflare.Artifacts.WriteNamespace(Repos)`): `create` / `delete` / `import`.
140 *
141 * @binding
142 * @product Artifacts
143 * @category Developer Platform
144 */
145export interface WriteNamespace extends Binding.Service<
146 WriteNamespace,
147 "Cloudflare.Artifacts.WriteNamespace",
148 (namespace: Artifacts.Namespace) => Effect.Effect<WriteNamespaceClient>
149> {}
150export const WriteNamespace = Binding.Service<WriteNamespace>(
151 "Cloudflare.Artifacts.WriteNamespace",
152);