@workers-community/workers-types 4.20260511.1 → 4.20260515.1

package/index.d.ts

@@ -11151,12 +11151,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",
@@ -11168,6 +11173,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>;
   // ── Fork ──
@@ -11175,6 +11181,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,
@@ -11185,13 +11194,53 @@ 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";
+/**
+ * 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,
@@ -11205,12 +11254,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: {
@@ -11238,6 +11298,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>;
 }
@@ -14750,6 +14811,9 @@ declare namespace TailStream {
     //  1. This is an Onset event
     //  2. We are not inheriting any SpanContext. (e.g. this is a cross-account service binding or a new top-level invocation)
     readonly spanId?: string;
+    // W3C trace flags from an upstream traceparent. Absent when no upstream
+    // sampling decision was made.
+    readonly traceFlags?: number;
   }
   interface TailEvent<Event extends EventType> {
     // invocation id of the currently invoked worker stage.

package/index.ts

@@ -11163,12 +11163,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",
@@ -11180,6 +11185,7 @@ 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 ──
@@ -11187,6 +11193,9 @@ export 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,
@@ -11197,13 +11206,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,
@@ -11217,12 +11266,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: {
@@ -11250,6 +11310,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>;
 }
@@ -14711,6 +14772,9 @@ export declare namespace TailStream {
     //  1. This is an Onset event
     //  2. We are not inheriting any SpanContext. (e.g. this is a cross-account service binding or a new top-level invocation)
     readonly spanId?: string;
+    // W3C trace flags from an upstream traceparent. Absent when no upstream
+    // sampling decision was made.
+    readonly traceFlags?: number;
   }
   interface TailEvent<Event extends EventType> {
     // invocation id of the currently invoked worker stage.

package/package.json

@@ -7,7 +7,7 @@
   },
   "author": "Workers Community",
   "license": "MIT OR Apache-2.0",
-  "version": "4.20260511.1",
+  "version": "4.20260515.1",
   "exports": {
     ".": {
       "types": "./index.d.ts",