Skip to content

feat: add ArtifactsError type definitions #6710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danlapid merged 4 commits into from
May 14, 2026
Merged

feat: add ArtifactsError type definitions #6710

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6b4a275
feat: add ArtifactsError and ArtifactsErrorCode type definitions
dmmulroy Apr 30, 2026
5b45871
chore: update generated workers types snapshots
dmmulroy May 1, 2026
23dfba2
docs: clarify Artifacts error codes
dmmulroy May 12, 2026
a9024c1
Merge branch 'main' into dillon/artifacts-error-types
dmmulroy May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 67 additions & 2 deletions types/defines/artifacts.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,12 +95,17 @@ interface ArtifactsTokenListResult {
total: number;
}

/** Handle for a single repository. Returned by Artifacts.get(). */
/**
* Handle for a single repository. Returned by Artifacts.get().
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
interface ArtifactsRepo extends ArtifactsRepoInfo {
/**
* Create an access token for this repo.
* @param scope Token scope: "write" (default) or "read".
* @param ttl Time-to-live in seconds (default 86400, min 60, max 31536000).
* @throws {ArtifactsError} with code `INVALID_TTL` if ttl is out of range.
*/
createToken(
scope?: 'write' | 'read',
Expand All @@ -114,6 +119,7 @@ interface ArtifactsRepo extends ArtifactsRepoInfo {
* Revoke a token by plaintext or ID.
* @param tokenOrId Plaintext token or token ID.
* @returns true if revoked, false if not found.
* @throws {ArtifactsError} with code `INVALID_INPUT` if tokenOrId is empty.
*/
revokeToken(tokenOrId: string): Promise<boolean>;

Expand All @@ -123,6 +129,9 @@ interface ArtifactsRepo extends ArtifactsRepoInfo {
* Fork this repo to a new repo.
* @param name Target repository name.
* @param opts Optional: description, readOnly flag, defaultBranchOnly (default true).
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if a fork is already running.
*/
fork(
name: string,
Expand All @@ -134,13 +143,57 @@ interface ArtifactsRepo extends ArtifactsRepoInfo {
): Promise<ArtifactsCreateRepoResult>;
}

/** Artifacts binding — namespace-level operations. */
// ── Error types ──────────────────────────────────────────────────────────────

/**
* Error codes returned by Artifacts binding operations.
*
* Each code maps to a numeric code available on `ArtifactsError.numericCode`.
*/
type ArtifactsErrorCode =
| 'ALREADY_EXISTS'
| 'NOT_FOUND'
| 'IMPORT_IN_PROGRESS'
| 'FORK_IN_PROGRESS'
| 'INVALID_INPUT'
| 'INVALID_REPO_NAME'
| 'INVALID_TTL'
| 'INVALID_URL'
| 'REMOTE_AUTH_REQUIRED'
| 'UPSTREAM_UNAVAILABLE'
| 'MEMORY_LIMIT'
| 'INTERNAL_ERROR';
Comment thread
dmmulroy marked this conversation as resolved.

/**
* Error thrown by Artifacts binding operations.
*
* Uses a string `.code` discriminator following the Cloudflare platform
* convention (StreamError, ImagesError, etc.). The `.numericCode` matches
* the REST API `errors[].code` values.
*/
interface ArtifactsError extends Error {
readonly name: 'ArtifactsError';
/** String error code for programmatic matching. */
readonly code: ArtifactsErrorCode;
/** Numeric error code matching the REST API. */
readonly numericCode: number;
}

// ── Binding ──────────────────────────────────────────────────────────────────

/**
* Artifacts binding — namespace-level operations.
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
interface Artifacts {
/**
* Create a new repository with an initial access token.
* @param name Repository name (alphanumeric, dots, hyphens, underscores).
* @param opts Optional: readOnly flag, description, default branch name.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the repo already exists.
*/
create(
name: string,
Expand All @@ -151,13 +204,24 @@ interface Artifacts {
* Get a handle to an existing repository.
* @param name Repository name.
* @returns Repo handle.
* @throws {ArtifactsError} with code `NOT_FOUND` if the repo does not exist.
* @throws {ArtifactsError} with code `IMPORT_IN_PROGRESS` if the repo is still importing.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if the repo is still forking.
*/
get(name: string): Promise<ArtifactsRepo>;

/**
* Import a repository from an external git remote.
* @param params Source URL and optional branch/depth, plus target name and options.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if the target name is invalid.
* @throws {ArtifactsError} with code `INVALID_INPUT` if the source URL is not valid HTTPS.
Comment thread
dmmulroy marked this conversation as resolved.
* @throws {ArtifactsError} with code `INVALID_URL` if the source URL does not point to a git repository.
* @throws {ArtifactsError} with code `REMOTE_AUTH_REQUIRED` if the remote requires authentication.
* @throws {ArtifactsError} with code `NOT_FOUND` if the remote repository does not exist.
* @throws {ArtifactsError} with code `UPSTREAM_UNAVAILABLE` if the remote cannot be reached.
* @throws {ArtifactsError} with code `MEMORY_LIMIT` if the import exceeds service memory limits.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
*/
import(params: {
source: {
Expand Down Expand Up @@ -187,6 +251,7 @@ interface Artifacts {
* Delete a repository and all associated tokens.
* @param name Repository name.
* @returns true if deleted, false if not found.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
*/
delete(name: string): Promise<boolean>;
}
65 changes: 63 additions & 2 deletions types/generated-snapshot/experimental/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11852,12 +11852,17 @@ interface ArtifactsTokenListResult {
/** Total number of tokens for the repository. */
total: number;
}
/** Handle for a single repository. Returned by Artifacts.get(). */
/**
* Handle for a single repository. Returned by Artifacts.get().
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
interface ArtifactsRepo extends ArtifactsRepoInfo {
/**
* Create an access token for this repo.
* @param scope Token scope: "write" (default) or "read".
* @param ttl Time-to-live in seconds (default 86400, min 60, max 31536000).
* @throws {ArtifactsError} with code `INVALID_TTL` if ttl is out of range.
*/
createToken(
scope?: "write" | "read",
Expand All @@ -11869,13 +11874,17 @@ interface ArtifactsRepo extends ArtifactsRepoInfo {
* Revoke a token by plaintext or ID.
* @param tokenOrId Plaintext token or token ID.
* @returns true if revoked, false if not found.
* @throws {ArtifactsError} with code `INVALID_INPUT` if tokenOrId is empty.
*/
revokeToken(tokenOrId: string): Promise<boolean>;
// ── Fork ──
/**
* Fork this repo to a new repo.
* @param name Target repository name.
* @param opts Optional: description, readOnly flag, defaultBranchOnly (default true).
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if a fork is already running.
*/
fork(
name: string,
Expand All @@ -11886,13 +11895,53 @@ interface ArtifactsRepo extends ArtifactsRepoInfo {
},
): Promise<ArtifactsCreateRepoResult>;
}
/** Artifacts binding — namespace-level operations. */
// ── Error types ──────────────────────────────────────────────────────────────
Comment thread
dmmulroy marked this conversation as resolved.
/**
* Error codes returned by Artifacts binding operations.
*
* Each code maps to a numeric code available on `ArtifactsError.numericCode`.
*/
type ArtifactsErrorCode =
| "ALREADY_EXISTS"
| "NOT_FOUND"
| "IMPORT_IN_PROGRESS"
| "FORK_IN_PROGRESS"
| "INVALID_INPUT"
| "INVALID_REPO_NAME"
| "INVALID_TTL"
| "INVALID_URL"
| "REMOTE_AUTH_REQUIRED"
| "UPSTREAM_UNAVAILABLE"
| "MEMORY_LIMIT"
| "INTERNAL_ERROR";
/**
* Error thrown by Artifacts binding operations.
*
* Uses a string `.code` discriminator following the Cloudflare platform
* convention (StreamError, ImagesError, etc.). The `.numericCode` matches
* the REST API `errors[].code` values.
*/
interface ArtifactsError extends Error {
readonly name: "ArtifactsError";
/** String error code for programmatic matching. */
readonly code: ArtifactsErrorCode;
/** Numeric error code matching the REST API. */
readonly numericCode: number;
}
// ── Binding ──────────────────────────────────────────────────────────────────
/**
* Artifacts binding — namespace-level operations.
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
interface Artifacts {
/**
* Create a new repository with an initial access token.
* @param name Repository name (alphanumeric, dots, hyphens, underscores).
* @param opts Optional: readOnly flag, description, default branch name.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the repo already exists.
*/
create(
name: string,
Expand All @@ -11906,12 +11955,23 @@ interface Artifacts {
* Get a handle to an existing repository.
* @param name Repository name.
* @returns Repo handle.
* @throws {ArtifactsError} with code `NOT_FOUND` if the repo does not exist.
* @throws {ArtifactsError} with code `IMPORT_IN_PROGRESS` if the repo is still importing.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if the repo is still forking.
*/
get(name: string): Promise<ArtifactsRepo>;
/**
* Import a repository from an external git remote.
* @param params Source URL and optional branch/depth, plus target name and options.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if the target name is invalid.
* @throws {ArtifactsError} with code `INVALID_INPUT` if the source URL is not valid HTTPS.
* @throws {ArtifactsError} with code `INVALID_URL` if the source URL does not point to a git repository.
* @throws {ArtifactsError} with code `REMOTE_AUTH_REQUIRED` if the remote requires authentication.
* @throws {ArtifactsError} with code `NOT_FOUND` if the remote repository does not exist.
* @throws {ArtifactsError} with code `UPSTREAM_UNAVAILABLE` if the remote cannot be reached.
* @throws {ArtifactsError} with code `MEMORY_LIMIT` if the import exceeds service memory limits.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
*/
import(params: {
source: {
Expand Down Expand Up @@ -11939,6 +11999,7 @@ interface Artifacts {
* Delete a repository and all associated tokens.
* @param name Repository name.
* @returns true if deleted, false if not found.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
*/
delete(name: string): Promise<boolean>;
}
Expand Down
65 changes: 63 additions & 2 deletions types/generated-snapshot/experimental/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11864,12 +11864,17 @@ export interface ArtifactsTokenListResult {
/** Total number of tokens for the repository. */
total: number;
}
/** Handle for a single repository. Returned by Artifacts.get(). */
/**
* Handle for a single repository. Returned by Artifacts.get().
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
export interface ArtifactsRepo extends ArtifactsRepoInfo {
/**
* Create an access token for this repo.
* @param scope Token scope: "write" (default) or "read".
* @param ttl Time-to-live in seconds (default 86400, min 60, max 31536000).
* @throws {ArtifactsError} with code `INVALID_TTL` if ttl is out of range.
*/
createToken(
scope?: "write" | "read",
Expand All @@ -11881,13 +11886,17 @@ export interface ArtifactsRepo extends ArtifactsRepoInfo {
* Revoke a token by plaintext or ID.
* @param tokenOrId Plaintext token or token ID.
* @returns true if revoked, false if not found.
* @throws {ArtifactsError} with code `INVALID_INPUT` if tokenOrId is empty.
*/
revokeToken(tokenOrId: string): Promise<boolean>;
// ── Fork ──
/**
* Fork this repo to a new repo.
* @param name Target repository name.
* @param opts Optional: description, readOnly flag, defaultBranchOnly (default true).
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if a fork is already running.
*/
fork(
name: string,
Expand All @@ -11898,13 +11907,53 @@ export interface ArtifactsRepo extends ArtifactsRepoInfo {
},
): Promise<ArtifactsCreateRepoResult>;
}
/** Artifacts binding — namespace-level operations. */
// ── Error types ──────────────────────────────────────────────────────────────
/**
* Error codes returned by Artifacts binding operations.
*
* Each code maps to a numeric code available on `ArtifactsError.numericCode`.
*/
export type ArtifactsErrorCode =
| "ALREADY_EXISTS"
| "NOT_FOUND"
| "IMPORT_IN_PROGRESS"
| "FORK_IN_PROGRESS"
| "INVALID_INPUT"
| "INVALID_REPO_NAME"
| "INVALID_TTL"
| "INVALID_URL"
| "REMOTE_AUTH_REQUIRED"
| "UPSTREAM_UNAVAILABLE"
| "MEMORY_LIMIT"
| "INTERNAL_ERROR";
/**
* Error thrown by Artifacts binding operations.
*
* Uses a string `.code` discriminator following the Cloudflare platform
* convention (StreamError, ImagesError, etc.). The `.numericCode` matches
* the REST API `errors[].code` values.
*/
export interface ArtifactsError extends Error {
readonly name: "ArtifactsError";
/** String error code for programmatic matching. */
readonly code: ArtifactsErrorCode;
/** Numeric error code matching the REST API. */
readonly numericCode: number;
}
// ── Binding ──────────────────────────────────────────────────────────────────
/**
* Artifacts binding — namespace-level operations.
*
* Methods may throw `ArtifactsError` with code `INTERNAL_ERROR` if an unexpected service error occurs.
*/
export interface Artifacts {
/**
* Create a new repository with an initial access token.
* @param name Repository name (alphanumeric, dots, hyphens, underscores).
* @param opts Optional: readOnly flag, description, default branch name.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the repo already exists.
*/
create(
name: string,
Expand All @@ -11918,12 +11967,23 @@ export interface Artifacts {
* Get a handle to an existing repository.
* @param name Repository name.
* @returns Repo handle.
* @throws {ArtifactsError} with code `NOT_FOUND` if the repo does not exist.
* @throws {ArtifactsError} with code `IMPORT_IN_PROGRESS` if the repo is still importing.
* @throws {ArtifactsError} with code `FORK_IN_PROGRESS` if the repo is still forking.
*/
get(name: string): Promise<ArtifactsRepo>;
/**
* Import a repository from an external git remote.
* @param params Source URL and optional branch/depth, plus target name and options.
* @returns Repo metadata with initial token.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if the target name is invalid.
* @throws {ArtifactsError} with code `INVALID_INPUT` if the source URL is not valid HTTPS.
* @throws {ArtifactsError} with code `INVALID_URL` if the source URL does not point to a git repository.
* @throws {ArtifactsError} with code `REMOTE_AUTH_REQUIRED` if the remote requires authentication.
* @throws {ArtifactsError} with code `NOT_FOUND` if the remote repository does not exist.
* @throws {ArtifactsError} with code `UPSTREAM_UNAVAILABLE` if the remote cannot be reached.
* @throws {ArtifactsError} with code `MEMORY_LIMIT` if the import exceeds service memory limits.
* @throws {ArtifactsError} with code `ALREADY_EXISTS` if the target repo already exists.
*/
import(params: {
source: {
Expand Down Expand Up @@ -11951,6 +12011,7 @@ export interface Artifacts {
* Delete a repository and all associated tokens.
* @param name Repository name.
* @returns true if deleted, false if not found.
* @throws {ArtifactsError} with code `INVALID_REPO_NAME` if name is invalid.
*/
delete(name: string): Promise<boolean>;
}
Expand Down
Loading
Loading