1
// Copyright (c) 2022-2025 Cloudflare, Inc.
2
// Licensed under the Apache 2.0 license found in the LICENSE file or at:
3
//     https://opensource.org/licenses/Apache-2.0
4
 
5
/**
6
 * Artifacts — Git-compatible file storage on Cloudflare Workers.
7
 *
8
 * Provides programmatic access to create, manage, and fork repositories,
9
 * and to issue and revoke scoped access tokens.
10
 */
11
 
12
/** Information about a repository. */
13
interface ArtifactsRepoInfo {
14
  /** Unique repository ID. */
15
  id: string;
16
  /** Repository name. */
17
  name: string;
18
  /** Repository description, or null if not set. */
19
  description: string | null;
20
  /** Default branch name (e.g. "main"). */
21
  defaultBranch: string;
22
  /** ISO 8601 creation timestamp. */
23
  createdAt: string;
24
  /** ISO 8601 last-updated timestamp. */
25
  updatedAt: string;
26
  /** ISO 8601 timestamp of the last push, or null if never pushed. */
27
  lastPushAt: string | null;
28
  /** Fork source (e.g. "github:owner/repo", "artifacts:namespace/repo"), or null if not a fork. */
29
  source: string | null;
30
  /** Whether the repository is read-only. */
31
  readOnly: boolean;
32
  /** HTTPS git remote URL. */
33
  remote: string;
34
}
35
 
36
/** Result of creating a repository — includes the initial access token. */
37
interface ArtifactsCreateRepoResult {
38
  /** Unique repository ID. */
39
  id: string;
40
  /** Repository name. */
41
  name: string;
42
  /** Repository description, or null if not set. */
43
  description: string | null;
44
  /** Default branch name. */
45
  defaultBranch: string;
46
  /** HTTPS git remote URL. */
47
  remote: string;
48
  /** Plaintext access token (only returned at creation time). */
49
  token: string;
50
  /** ISO 8601 token expiry timestamp. */
51
  tokenExpiresAt: string;
52
}
53
 
54
/** Paginated list of repositories. */
55
interface ArtifactsRepoListResult {
56
  /** Repositories in this page (without the `remote` field). */
57
  repos: Omit<ArtifactsRepoInfo, 'remote'>[];
58
  /** Total number of repositories in the namespace. */
59
  total: number;
60
  /** Cursor for the next page, if there are more results. */
61
  cursor?: string;
62
}
63
 
64
/** Result of creating an access token. */
65
interface ArtifactsCreateTokenResult {
66
  /** Unique token ID. */
67
  id: string;
68
  /** Plaintext token (only returned at creation time). */
69
  plaintext: string;
70
  /** Token scope: "read" or "write". */
71
  scope: 'read' | 'write';
72
  /** ISO 8601 token expiry timestamp. */
73
  expiresAt: string;
74
}
75
 
76
/** Token metadata (no plaintext). */
77
interface ArtifactsTokenInfo {
78
  /** Unique token ID. */
79
  id: string;
80
  /** Token scope: "read" or "write". */
81
  scope: 'read' | 'write';
82
  /** Token state: "active", "expired", or "revoked". */
83
  state: 'active' | 'expired' | 'revoked';
84
  /** ISO 8601 creation timestamp. */
85
  createdAt: string;
86
  /** ISO 8601 expiry timestamp. */
87
  expiresAt: string;
88
}
89
 
90
/** Paginated list of tokens for a repository. */
91
interface ArtifactsTokenListResult {
92
  /** Tokens in this page. */
93
  tokens: ArtifactsTokenInfo[];
94
  /** Total number of tokens for the repository. */
95
  total: number;
96
}
97
 
98
/**
99
 * Handle for a single repository. Returned by Artifacts.get().
100
 *
101
 * Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
102
 */
103
interface ArtifactsRepo extends ArtifactsRepoInfo {
104
  /**
105
   * Create an access token for this repo.
106
   * @param scope Token scope: "write" (default) or "read".
107
   * @param ttl Time-to-live in seconds (default 86400, min 60, max 31536000).
108
   * @throws {ArtifactsError} with code `INVALID_TTL` if ttl is out of range.
109
   */
110
  createToken(
111
    scope?: 'write' | 'read',
112
    ttl?: number
113
  ): Promise<ArtifactsCreateTokenResult>;
114
 
115
  /** List tokens for this repo (metadata only, no plaintext). */
116
  listTokens(): Promise<ArtifactsTokenListResult>;
117
 
118
  /**
119
   * Revoke a token by plaintext or ID.
120
   * @param tokenOrId Plaintext token or token ID.
121
   * @returns true if revoked, false if not found.
122
   * @throws {ArtifactsError} with code `INVALID_INPUT` if tokenOrId is empty.
123
   */
124
  revokeToken(tokenOrId: string): Promise<boolean>;
125
 
126
  // ── Fork ──
127
 
128
  /**
129
   * Fork this repo to a new repo.
130
   * @param name Target repository name.
131
   * @param opts Optional: description, readOnly flag, defaultBranchOnly (default true).
132
   * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
133
   * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
134
   * @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if a fork is already running.
135
   */
136
  fork(
137
    name: string,
138
    opts?: {
139
      description?: string;
140
      readOnly?: boolean;
141
      defaultBranchOnly?: boolean;
142
    }
143
  ): Promise<ArtifactsCreateRepoResult>;
144
}
145
 
146
// ── Error types ──────────────────────────────────────────────────────────────
147
 
148
/**
149
 * Error codes returned by Artifacts binding operations.
150
 *
151
 * Each code maps to a numeric code available on `ArtifactsError.numericCode`.
152
 */
153
type ArtifactsErrorCode =
154
  | 'ALREADY_EXISTS'
155
  | 'NOT_FOUND'
156
  | 'IMPORT_IN_PROGRESS'
157
  | 'FORK_IN_PROGRESS'
158
  | 'INVALID_INPUT'
159
  | 'INVALID_REPO_NAME'
160
  | 'INVALID_TTL'
161
  | 'INVALID_URL'
162
  | 'REMOTE_AUTH_REQUIRED'
163
  | 'UPSTREAM_UNAVAILABLE'
164
  | 'MEMORY_LIMIT'
165
  | 'INTERNAL_ERROR';
166
 
167
/**
168
 * Error thrown by Artifacts binding operations.
169
 *
170
 * Uses a string `.code` discriminator following the Cloudflare platform
171
 * convention (StreamError, ImagesError, etc.). The `.numericCode` matches
172
 * the REST API `errors[].code` values.
173
 */
174
interface ArtifactsError extends Error {
175
  readonly name: 'ArtifactsError';
176
  /** String error code for programmatic matching. */
177
  readonly code: ArtifactsErrorCode;
178
  /** Numeric error code matching the REST API. */
179
  readonly numericCode: number;
180
}
181
 
182
// ── Binding ──────────────────────────────────────────────────────────────────
183
 
184
/**
185
 * Artifacts binding — namespace-level operations.
186
 *
187
 * Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
188
 */
189
interface Artifacts {
190
  /**
191
   * Create a new repository with an initial access token.
192
   * @param name Repository name (alphanumeric, dots, hyphens, underscores).
193
   * @param opts Optional: readOnly flag, description, default branch name.
194
   * @returns Repo metadata with initial token.
195
   * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
196
   * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the repo already exists.
197
   */
198
  create(
199
    name: string,
200
    opts?: { readOnly?: boolean; description?: string; setDefaultBranch?: string }
201
  ): Promise<ArtifactsCreateRepoResult>;
202
 
203
  /**
204
   * Get a handle to an existing repository.
205
   * @param name Repository name.
206
   * @returns Repo handle.
207
   * @throws {ArtifactsError} with code `NOT_FOUND` if the repo does not exist.
208
   * @throws {ArtifactsError} with code `IMPORT_IN_PROGRESS` if the repo is still importing.
209
   * @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if the repo is still forking.
210
   */
211
  get(name: string): Promise<ArtifactsRepo>;
212
 
213
  /**
214
   * Import a repository from an external git remote.
215
   * @param params Source URL and optional branch/depth, plus target name and options.
216
   * @returns Repo metadata with initial token.
217
   * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if the target name is invalid.
218
   * @throws {ArtifactsError} with code `INVALID_INPUT` if the source URL is not valid HTTPS.
219
   * @throws {ArtifactsError} with code `INVALID_URL` if the source URL does not point to a git repository.
220
   * @throws {ArtifactsError} with code `REMOTE_AUTH_REQUIRED` if the remote requires authentication.
221
   * @throws {ArtifactsError} with code `NOT_FOUND` if the remote repository does not exist.
222
   * @throws {ArtifactsError} with code `UPSTREAM_UNAVAILABLE` if the remote cannot be reached.
223
   * @throws {ArtifactsError} with code `MEMORY_LIMIT` if the import exceeds service memory limits.
224
   * @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
225
   */
226
  import(params: {
227
    source: {
228
      url: string;
229
      branch?: string;
230
      depth?: number;
231
    };
232
    target: {
233
      name: string;
234
      opts?: {
235
        description?: string;
236
        readOnly?: boolean;
237
      };
238
    };
239
  }): Promise<ArtifactsCreateRepoResult>;
240
 
241
  /**
242
   * List repositories with cursor-based pagination.
243
   * @param opts Optional: limit (1–200, default 50), cursor for next page.
244
   */
245
  list(opts?: {
246
    limit?: number;
247
    cursor?: string;
248
  }): Promise<ArtifactsRepoListResult>;
249
 
250
  /**
251
   * Delete a repository and all associated tokens.
252
   * @param name Repository name.
253
   * @returns true if deleted, false if not found.
254
   * @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
255
   */
256
  delete(name: string): Promise<boolean>;
257
}