@gibwork/sdk 0.0.6 → 0.1.0

package/dist/index.d.ts

@@ -18,8 +18,9 @@ declare class GibworkApiError extends GibworkError {
     readonly method: string;
     readonly path: string;
     readonly requestId?: string | undefined;
+    readonly retryAfter?: string | undefined;
     readonly name: string;
-    constructor(status: number, body: unknown, method: string, path: string, requestId?: string | undefined);
+    constructor(status: number, body: unknown, method: string, path: string, requestId?: string | undefined, retryAfter?: string | undefined);
 }
 declare class GibworkNetworkError extends GibworkError {
     readonly method: string;
@@ -36,18 +37,46 @@ declare class GibworkRequestAbortedError extends GibworkNetworkError {
     readonly name: string;
     constructor(method: string, path: string, options?: ErrorOptions);
 }
-type SubmitOperation = 'create-task' | 'refund-task' | 'approve-submission';
+type SubmitOperation = 'create-task' | 'refund-task' | 'approve-submission' | 'create-submission';
 interface AmbiguousSubmitContext {
     operation: SubmitOperation;
     taskId?: string;
     submissionId?: string;
     intentId: string;
+    paymentAttemptId?: string;
+    idempotencyKey?: string;
+    walletAddress?: string;
+    environment?: 'stage' | 'prod';
+    apiUrl?: string;
 }
 declare class GibworkAmbiguousSubmitError extends GibworkNetworkError {
     readonly context: AmbiguousSubmitContext;
     readonly name: string;
     constructor(method: string, path: string, context: AmbiguousSubmitContext, options?: ErrorOptions);
 }
+declare class GibworkValidationError extends GibworkError {
+    readonly name: string;
+}
+declare class GibworkProtocolError extends GibworkError {
+    readonly name: string;
+}
+interface SubmissionRecoveryContext {
+    taskId: string;
+    idempotencyKey: string;
+    walletAddress: string;
+    environment: 'stage' | 'prod';
+    apiUrl: string;
+    phase: 'prepare' | 'sign' | 'submit';
+    intentId?: string;
+    paymentAttemptId?: string;
+    submissionId?: string;
+}
+/** Retains identifiers when creation stops, including before any payment is sent. */
+declare class GibworkSubmissionOperationError extends GibworkError {
+    readonly context: SubmissionRecoveryContext;
+    readonly name: string;
+    constructor(context: SubmissionRecoveryContext, options?: ErrorOptions);
+}
 
 interface RequestOptions {
     signal?: AbortSignal;
@@ -325,6 +354,88 @@ interface GibworkApiErrorBody {
     error?: string;
     [key: string]: unknown;
 }
+interface AvailableTasksQuery {
+    page?: number;
+    limit?: number;
+}
+interface AvailableTask {
+    id: string;
+    slug: string;
+    title: string;
+    content: string;
+    requirements: string | null;
+    tags: string[];
+    primarySkillId: string | null;
+    createdAt: string;
+    deadline: string | null;
+    status: 'CREATED';
+    isOpen: boolean;
+    asset: AvailableTaskAsset | null;
+    minSubmissionAmount: string | null;
+    totalSubmissions: number;
+    maxSubmissions: number | null;
+    standardSubmissionSlotsRemaining: number | null;
+    requiresPremium: boolean;
+    participationRequirements: AvailableTaskParticipationRequirements;
+}
+type AvailableTaskPage = Paginated<AvailableTask>;
+interface CreateSubmissionInput {
+    content: string;
+    referral?: string | null;
+    mediaIds?: string[] | null;
+    /** Reuse for retries of this exact task and submission payload. */
+    idempotencyKey: string;
+}
+interface SubmitSubmissionInput {
+    paymentAttemptId: string;
+    signedTransaction: string;
+}
+type TaskSubmissionIntentStatus = 'pending' | 'submitted' | 'fulfilled' | 'failed' | 'expired' | 'requires_review';
+interface TaskSubmissionIntent {
+    intentId: string;
+    taskId: string;
+    /** Allocated in advance; exists as a submission only when fulfilled. */
+    taskSubmissionId: string;
+    paymentAttemptId: string;
+    status: TaskSubmissionIntentStatus;
+    txHash: string | null;
+    expiresAt: string;
+    lastValidBlockHeight: number;
+    fee: TaskSubmissionFee;
+    reviewReason?: string;
+    /** Only returned by prepare for a pending intent, including pending retries. */
+    serializedTransaction?: string;
+}
+interface TaskSubmissionFee {
+    amount: string;
+    amountBaseUnits: string;
+    totalDebit: string;
+    symbol: 'USDC';
+    mintAddress: string;
+    decimals: number;
+    destinationAddress: string;
+}
+interface AvailableTaskAsset {
+    mintAddress: string;
+    symbol: string;
+    imageUrl: string;
+    decimals: number;
+    /** Original reward pool in base units, not the remaining balance. */
+    amount: string;
+}
+interface AvailableTaskParticipationRequirements {
+    allowOnlyVerifiedSubmissions: boolean;
+    allowOnlyVerifiedTwitterAccountSubmissions: boolean;
+    minTwitterFollowers: number;
+    minTweetLikes: number;
+    minTweetViews: number;
+    isTwitterTask: boolean;
+    allowOnlyDiscordGuildSubmissions: boolean;
+    requiredDiscordGuildId: string | null;
+    requiredDiscordGuildName: string | null;
+    discordGuildInvitationUrl: string | null;
+    requiredDiscordRoleIds: string[];
+}
 
 type FetchImplementation = typeof fetch;
 interface HttpTransportOptions {
@@ -340,6 +451,7 @@ interface HttpRequest {
     body?: unknown;
     options?: RequestOptions;
     ambiguousSubmit?: AmbiguousSubmitContext;
+    validateResponse?: (body: unknown) => void;
 }
 declare class HttpTransport {
     private readonly baseUrl;
@@ -347,6 +459,11 @@ declare class HttpTransport {
     private readonly production;
     private readonly timeoutMs;
     constructor(options: HttpTransportOptions);
+    /** Recovery location without URL credentials. Retains reverse-proxy path prefixes. */
+    get recoveryLocation(): {
+        apiUrl: string;
+        environment: 'stage' | 'prod';
+    };
     request<T>(request: HttpRequest): Promise<T>;
 }
 
@@ -363,6 +480,14 @@ declare class SubmissionsResource {
     private readonly signer;
     readonly comments: SubmissionCommentsResource;
     constructor(transport: HttpTransport, signer: WalletSigner);
+    /** Creates work through a participation fee; only fulfilled confirms creation. */
+    create(taskId: string, input: CreateSubmissionInput, options?: RequestOptions): Promise<TaskSubmissionIntent>;
+    /** Reuse the exact input and idempotency key after an interrupted prepare. */
+    prepareCreate(taskId: string, input: CreateSubmissionInput, options?: RequestOptions): Promise<TaskSubmissionIntent>;
+    /** Never automatically retries. Recover an uncertain payment with getIntent. */
+    submitCreate(taskId: string, intentId: string, input: SubmitSubmissionInput, options?: RequestOptions): Promise<TaskSubmissionIntent>;
+    /** Reads/reconciles creation using the original wallet; does not report review/payout. */
+    getIntent(taskId: string, intentId: string, options?: RequestOptions): Promise<TaskSubmissionIntent>;
     list(taskId: string, query?: SubmissionPaginationQuery, options?: RequestOptions): Promise<Paginated<TaskSubmission>>;
     get(taskId: string, submissionId: string, options?: RequestOptions): Promise<WalletTaskSubmissionDetails>;
     approve(taskId: string, submissionId: string, input: ApproveSubmissionInput, options?: RequestOptions): Promise<ApproveSubmissionResult>;
@@ -378,6 +503,8 @@ declare class TasksResource {
     constructor(transport: HttpTransport, signer: WalletSigner);
     create(input: CreateTaskInput, options?: RequestOptions): Promise<CreateTaskResult>;
     list(query?: PaginationQuery, options?: RequestOptions): Promise<Paginated<WalletTaskSummary>>;
+    /** Discover tasks across creators. Eligibility is checked when preparing work. */
+    listAvailable(query?: AvailableTasksQuery, options?: RequestOptions): Promise<AvailableTaskPage>;
     update(taskId: string, input: UpdateTaskInput, options?: RequestOptions): Promise<UpdatedTask>;
     refund(taskId: string, options?: RequestOptions): Promise<RefundTaskResult>;
     prepareCreate(input: CreateTaskInput, options?: RequestOptions): Promise<PreparedTaskIntent>;
@@ -407,4 +534,4 @@ declare const DEFAULT_GIBWORK_API_URL: string;
 
 declare function signPreparedTransaction(serializedTransaction: string, signer: WalletSigner): Promise<string>;
 
-export { type AmbiguousSubmitContext, type ApprovalQuote, type ApprovalSubmitResult, type ApproveSubmissionInput, type ApproveSubmissionResult, type CreateTaskInput, type CreateTaskResult, DEFAULT_GIBWORK_API_URL, type FeeQuote, type FetchImplementation, GibworkAmbiguousSubmitError, GibworkApiError, type GibworkApiErrorBody, GibworkClient, type GibworkClientOptions, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkRequestAbortedError, GibworkTimeoutError, type MediaItem, type Membership, type Paginated, type PaginationQuery, type PaymentQuote, type PreparedApprovalIntent, type PreparedRefundIntent, type PreparedTaskIntent, type PublicProfileReference, type RefundQuote, type RefundSubmitResult, type RefundTaskResult, type RejectSubmissionResult, type RequestOptions, type SubmissionAsset, type SubmissionComment, type SubmissionPaginationQuery, type SubmissionStatus, type SubmitOperation, type TaskSubmission, type TaskSubmissionStatus, type TaskSubmitResult, type TokenQuote, type UpdateTaskInput, type UpdatedTask, type UserSummary, type WalletSigner, type WalletSubmissionComment, type WalletSubmissionUser, type WalletTaskAsset, type WalletTaskSubmissionDetails, type WalletTaskSummary, signPreparedTransaction };
+export { type AmbiguousSubmitContext, type ApprovalQuote, type ApprovalSubmitResult, type ApproveSubmissionInput, type ApproveSubmissionResult, type AvailableTask, type AvailableTaskAsset, type AvailableTaskPage, type AvailableTaskParticipationRequirements, type AvailableTasksQuery, type CreateSubmissionInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_GIBWORK_API_URL, type FeeQuote, type FetchImplementation, GibworkAmbiguousSubmitError, GibworkApiError, type GibworkApiErrorBody, GibworkClient, type GibworkClientOptions, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkProtocolError, GibworkRequestAbortedError, GibworkSubmissionOperationError, GibworkTimeoutError, GibworkValidationError, type MediaItem, type Membership, type Paginated, type PaginationQuery, type PaymentQuote, type PreparedApprovalIntent, type PreparedRefundIntent, type PreparedTaskIntent, type PublicProfileReference, type RefundQuote, type RefundSubmitResult, type RefundTaskResult, type RejectSubmissionResult, type RequestOptions, type SubmissionAsset, type SubmissionComment, type SubmissionPaginationQuery, type SubmissionRecoveryContext, type SubmissionStatus, type SubmitOperation, type SubmitSubmissionInput, type TaskSubmission, type TaskSubmissionFee, type TaskSubmissionIntent, type TaskSubmissionIntentStatus, type TaskSubmissionStatus, type TaskSubmitResult, type TokenQuote, type UpdateTaskInput, type UpdatedTask, type UserSummary, type WalletSigner, type WalletSubmissionComment, type WalletSubmissionUser, type WalletTaskAsset, type WalletTaskSubmissionDetails, type WalletTaskSummary, signPreparedTransaction };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { DEFAULT_GIBWORK_API_URL, GibworkAmbiguousSubmitError, GibworkApiError, GibworkClient, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkRequestAbortedError, GibworkTimeoutError, signPreparedTransaction } from './chunk-3MLFNEQ5.js';
+export { DEFAULT_GIBWORK_API_URL, GibworkAmbiguousSubmitError, GibworkApiError, GibworkClient, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkProtocolError, GibworkRequestAbortedError, GibworkSubmissionOperationError, GibworkTimeoutError, GibworkValidationError, signPreparedTransaction } from './chunk-HJ5D5SOE.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/node.cjs

@@ -24,19 +24,21 @@ var GibworkConfigurationError = class extends GibworkError {
   name = "GibworkConfigurationError";
 };
 var GibworkApiError = class extends GibworkError {
-  constructor(status, body, method, path, requestId) {
+  constructor(status, body, method, path, requestId, retryAfter) {
     super(`Gibwork API request failed with HTTP ${status}`);
     this.status = status;
     this.body = body;
     this.method = method;
     this.path = path;
     this.requestId = requestId;
+    this.retryAfter = retryAfter;
   }
   status;
   body;
   method;
   path;
   requestId;
+  retryAfter;
   name = "GibworkApiError";
 };
 var GibworkNetworkError = class extends GibworkError {
@@ -81,6 +83,51 @@ var GibworkAmbiguousSubmitError = class extends GibworkNetworkError {
   context;
   name = "GibworkAmbiguousSubmitError";
 };
+var GibworkValidationError = class extends GibworkError {
+  name = "GibworkValidationError";
+};
+var GibworkProtocolError = class extends GibworkError {
+  name = "GibworkProtocolError";
+};
+var GibworkSubmissionOperationError = class extends GibworkError {
+  constructor(context, options) {
+    super(
+      "Submission creation interrupted; recover using the original input/key or intent",
+      options
+    );
+    this.context = context;
+  }
+  context;
+  name = "GibworkSubmissionOperationError";
+};
+
+// src/auth/validation.ts
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertObjectKeys(value, keys) {
+  if (!isRecord(value) || Object.keys(value).some((key) => !keys.includes(key))) {
+    throw new GibworkValidationError(
+      `Expected an object containing only: ${keys.join(", ")}`
+    );
+  }
+}
+function isUuid(value, v4 = false) {
+  return typeof value === "string" && (v4 ? UUID_V4 : UUID).test(value);
+}
+function assertUuid(value, name, v4 = false) {
+  if (!isUuid(value, v4))
+    throw new GibworkValidationError(`${name} must be a UUID${v4 ? "v4" : ""}`);
+}
+function assertText(value, name, min, max) {
+  if (typeof value !== "string" || Array.from(value).length < min || Array.from(value).length > max) {
+    throw new GibworkValidationError(
+      `${name} must contain ${min}\u2013${max} characters`
+    );
+  }
+}
 var HTML_SANITIZE_OPTIONS = {
   allowedTags: sanitizeHtml__default.default.defaults.allowedTags.concat(["img"]),
   allowedAttributes: {
@@ -235,6 +282,42 @@ function trimOptional(value) {
   const trimmed = value.trim();
   return trimmed === "" ? void 0 : trimmed;
 }
+function normalizeAvailableTasksQuery(query = {}) {
+  assertObjectKeys(query, ["page", "limit"]);
+  const page = query.page === void 0 ? 1 : query.page;
+  const limit = query.limit === void 0 ? 15 : query.limit;
+  if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger((page - 1) * limit)) {
+    throw new GibworkValidationError(
+      "page must be a positive safe integer, limit must be 1\u2013100, and the offset must be safe"
+    );
+  }
+  return { page, limit };
+}
+function normalizeCreateSubmission(input, walletAddress) {
+  assertObjectKeys(input, [
+    "content",
+    "referral",
+    "mediaIds",
+    "idempotencyKey"
+  ]);
+  assertText(input.content, "content", 1, 5e4);
+  if (input.referral != null) assertText(input.referral, "referral", 0, 200);
+  assertUuid(input.idempotencyKey, "idempotencyKey", true);
+  const mediaIds = input.mediaIds ?? [];
+  if (!Array.isArray(mediaIds) || mediaIds.length > 10 || new Set(mediaIds).size !== mediaIds.length) {
+    throw new GibworkValidationError(
+      "mediaIds must contain at most ten distinct UUIDv4 values"
+    );
+  }
+  for (const id of mediaIds) assertUuid(id, "mediaIds", true);
+  return {
+    walletAddress,
+    content: input.content,
+    referral: input.referral ?? null,
+    mediaIds: [...mediaIds],
+    idempotencyKey: input.idempotencyKey
+  };
+}
 async function createWalletAuthHeaders(signer, descriptor, dependencies = {}) {
   const values = {
     walletAddress: signer.publicKey.toBase58(),
@@ -271,6 +354,30 @@ function buildWalletAuthMessage(descriptor, values) {
     `${descriptor.hash[0]}:${descriptor.hash[1]}`
   ].join("\n");
 }
+
+// src/resources/submissions/submission-intent.ts
+function submissionIntentPath(taskId, intentId) {
+  assertUuid(taskId, "taskId");
+  if (intentId !== void 0) assertUuid(intentId, "intentId");
+  return `/v2/int/tasks/${taskId}/submission-intents${intentId === void 0 ? "" : `/${intentId}`}`;
+}
+var statuses = [
+  "pending",
+  "submitted",
+  "fulfilled",
+  "failed",
+  "expired",
+  "requires_review"
+];
+var nonempty = (value) => typeof value === "string" && value.length > 0;
+var decimal = (value) => typeof value === "string" && /^\d+(\.\d+)?$/.test(value);
+var natural = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+var sameId = (value, expected) => value.toLowerCase() === expected.toLowerCase();
+function validateSubmissionIntent(value, taskId, intentId, paymentAttemptId) {
+  if (!isRecord(value) || !isUuid(value.intentId) || !isUuid(value.taskId) || !isUuid(value.taskSubmissionId) || !isUuid(value.paymentAttemptId, true) || !sameId(value.taskId, taskId) || intentId !== void 0 && !sameId(value.intentId, intentId) || paymentAttemptId !== void 0 && !sameId(value.paymentAttemptId, paymentAttemptId) || typeof value.status !== "string" || !statuses.includes(value.status) || !(value.txHash === null || nonempty(value.txHash)) || !nonempty(value.expiresAt) || !Number.isFinite(Date.parse(value.expiresAt)) || !natural(value.lastValidBlockHeight) || value.reviewReason !== void 0 && typeof value.reviewReason !== "string" || value.serializedTransaction !== void 0 && !nonempty(value.serializedTransaction) || !isRecord(value.fee) || !decimal(value.fee.amount) || !decimal(value.fee.totalDebit) || typeof value.fee.amountBaseUnits !== "string" || !/^\d+$/.test(value.fee.amountBaseUnits) || value.fee.symbol !== "USDC" || !natural(value.fee.decimals) || !nonempty(value.fee.mintAddress) || !nonempty(value.fee.destinationAddress)) {
+    throw new GibworkProtocolError("Invalid submission intent response");
+  }
+}
 async function signPreparedTransaction(serializedTransaction, signer) {
   if (typeof serializedTransaction !== "string" || !serializedTransaction) {
     throw new GibworkConfigurationError(
@@ -360,6 +467,142 @@ var SubmissionsResource = class {
   transport;
   signer;
   comments;
+  /** Creates work through a participation fee; only fulfilled confirms creation. */
+  async create(taskId, input, options) {
+    const path = submissionIntentPath(taskId);
+    const { walletAddress, ...snapshot } = normalizeCreateSubmission(
+      input,
+      this.walletAddress
+    );
+    let context = {
+      taskId,
+      idempotencyKey: snapshot.idempotencyKey,
+      walletAddress,
+      ...this.transport.recoveryLocation,
+      phase: "prepare"
+    };
+    try {
+      assertNotAborted(options, path);
+      const prepared = await this.prepareCreate(taskId, snapshot, options);
+      context = {
+        ...context,
+        intentId: prepared.intentId,
+        paymentAttemptId: prepared.paymentAttemptId,
+        submissionId: prepared.taskSubmissionId,
+        phase: "sign"
+      };
+      if (prepared.status !== "pending") return prepared;
+      if (!prepared.serializedTransaction)
+        throw new GibworkProtocolError(
+          "Pending prepare response is missing its transaction"
+        );
+      assertNotAborted(options, path);
+      const signedTransaction = await signPreparedTransaction(
+        prepared.serializedTransaction,
+        this.signer
+      );
+      assertNotAborted(options, path);
+      context = { ...context, phase: "submit" };
+      return await this.submitCreate(
+        taskId,
+        prepared.intentId,
+        { paymentAttemptId: prepared.paymentAttemptId, signedTransaction },
+        options
+      );
+    } catch (cause) {
+      if (cause instanceof GibworkAmbiguousSubmitError) {
+        throw new GibworkAmbiguousSubmitError(
+          cause.method,
+          cause.path,
+          {
+            ...cause.context,
+            ...context,
+            operation: "create-submission",
+            intentId: cause.context.intentId
+          },
+          { cause }
+        );
+      }
+      throw new GibworkSubmissionOperationError(context, { cause });
+    }
+  }
+  /** Reuse the exact input and idempotency key after an interrupted prepare. */
+  async prepareCreate(taskId, input, options) {
+    const path = submissionIntentPath(taskId);
+    const body = normalizeCreateSubmission(input, this.walletAddress);
+    assertNotAborted(options, path);
+    const headers = await createWalletAuthHeaders(this.signer, {
+      operation: "gibwork:create-task-submission-intent",
+      method: "POST",
+      path,
+      resourceFields: [["taskId", taskId]],
+      hash: ["payloadHash", sha256Json(body)]
+    });
+    return this.transport.request({
+      method: "POST",
+      path,
+      headers,
+      body,
+      ...options ? { options } : {},
+      validateResponse: (value) => validateSubmissionIntent(value, taskId)
+    });
+  }
+  /** Never automatically retries. Recover an uncertain payment with getIntent. */
+  async submitCreate(taskId, intentId, input, options) {
+    const path = `${submissionIntentPath(taskId, intentId)}/submit`;
+    assertObjectKeys(input, ["paymentAttemptId", "signedTransaction"]);
+    assertUuid(input.paymentAttemptId, "paymentAttemptId", true);
+    assertText(input.signedTransaction, "signedTransaction", 1, 1e4);
+    const body = {
+      paymentAttemptId: input.paymentAttemptId,
+      signedTransaction: input.signedTransaction
+    };
+    return this.transport.request({
+      method: "POST",
+      path,
+      body,
+      ...options ? { options } : {},
+      ambiguousSubmit: {
+        operation: "create-submission",
+        taskId,
+        intentId,
+        paymentAttemptId: body.paymentAttemptId,
+        walletAddress: this.walletAddress,
+        ...this.transport.recoveryLocation
+      },
+      validateResponse: (value) => validateSubmissionIntent(
+        value,
+        taskId,
+        intentId,
+        body.paymentAttemptId
+      )
+    });
+  }
+  /** Reads/reconciles creation using the original wallet; does not report review/payout. */
+  async getIntent(taskId, intentId, options) {
+    const path = submissionIntentPath(taskId, intentId);
+    if (options?.signal?.aborted)
+      throw new GibworkRequestAbortedError("GET", path, {
+        cause: options.signal.reason
+      });
+    const headers = await createWalletAuthHeaders(this.signer, {
+      operation: "gibwork:view-task-submission-intent",
+      method: "GET",
+      path,
+      resourceFields: [
+        ["taskId", taskId],
+        ["intentId", intentId]
+      ],
+      hash: ["queryHash", sha256Json({})]
+    });
+    return this.transport.request({
+      method: "GET",
+      path,
+      headers,
+      ...options ? { options } : {},
+      validateResponse: (value) => validateSubmissionIntent(value, taskId, intentId)
+    });
+  }
   async list(taskId, query = {}, options) {
     const normalized = normalizeSubmissionPagination(query);
     const path = `/v2/int/tasks/${encodeURIComponent(taskId)}/submissions`;
@@ -549,6 +792,23 @@ var TasksResource = class {
       ...options ? { options } : {}
     });
   }
+  /** Discover tasks across creators. Eligibility is checked when preparing work. */
+  async listAvailable(query = {}, options) {
+    const normalized = normalizeAvailableTasksQuery(query);
+    const path = "/v2/int/tasks/available";
+    const headers = await this.auth({
+      operation: "gibwork:view-available-tasks",
+      method: "GET",
+      path,
+      hash: ["queryHash", sha256Json(normalized)]
+    });
+    return this.transport.request({
+      method: "GET",
+      path: `${path}?${toQueryString(normalized)}`,
+      headers,
+      ...options ? { options } : {}
+    });
+  }
   async update(taskId, input, options) {
     const path = `/v2/int/tasks/${encodeURIComponent(taskId)}`;
     const body = normalizeUpdateTask(input, this.walletAddress);
@@ -694,6 +954,16 @@ var HttpTransport = class {
       );
     }
   }
+  /** Recovery location without URL credentials. Retains reverse-proxy path prefixes. */
+  get recoveryLocation() {
+    const url = new URL(this.baseUrl);
+    url.username = "";
+    url.password = "";
+    return {
+      apiUrl: url.toString().replace(/\/+$/, ""),
+      environment: this.production ? "prod" : "stage"
+    };
+  }
   async request(request) {
     const controller = new AbortController();
     const callerSignal = request.options?.signal;
@@ -703,12 +973,6 @@ var HttpTransport = class {
         cause: callerSignal.reason
       });
     }
-    const abortFromCaller = () => controller.abort(callerSignal?.reason);
-    callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
-    const timeout = setTimeout(() => {
-      timedOut = true;
-      controller.abort();
-    }, this.timeoutMs);
     const headers = {
       accept: "application/json",
       ...request.headers,
@@ -723,13 +987,40 @@ var HttpTransport = class {
       headers["content-type"] = "application/json";
       init.body = JSON.stringify(request.body);
     }
-    let response;
+    const abortFromCaller = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
+    let rejectOnAbort = () => {
+    };
+    const aborted = new Promise((_, reject) => {
+      rejectOnAbort = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", rejectOnAbort, {
+        once: true
+      });
+    });
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeoutMs);
     try {
-      response = await this.fetchImplementation(
-        `${this.baseUrl}${request.path}`,
-        init
-      );
+      const response = await Promise.race([
+        this.fetchImplementation(`${this.baseUrl}${request.path}`, init),
+        aborted
+      ]);
+      const body = await Promise.race([parseResponseBody(response), aborted]);
+      if (!response.ok) {
+        throw new GibworkApiError(
+          response.status,
+          body,
+          request.method,
+          request.path,
+          response.headers.get("x-request-id") ?? void 0,
+          response.headers.get("retry-after") ?? void 0
+        );
+      }
+      request.validateResponse?.(body);
+      return body;
     } catch (cause) {
+      if (cause instanceof GibworkApiError && cause.status < 500) throw cause;
       if (request.ambiguousSubmit) {
         throw new GibworkAmbiguousSubmitError(
           request.method,
@@ -738,6 +1029,8 @@ var HttpTransport = class {
           { cause }
         );
       }
+      if (cause instanceof GibworkApiError || cause instanceof GibworkProtocolError)
+        throw cause;
       if (timedOut) {
         throw new GibworkTimeoutError(
           request.method,
@@ -752,7 +1045,7 @@ var HttpTransport = class {
         });
       }
       throw new GibworkNetworkError(
-        "Could not reach the Gibwork API",
+        "Could not read the Gibwork API response",
         request.method,
         request.path,
         { cause }
@@ -760,28 +1053,8 @@ var HttpTransport = class {
     } finally {
       clearTimeout(timeout);
       callerSignal?.removeEventListener("abort", abortFromCaller);
+      controller.signal.removeEventListener("abort", rejectOnAbort);
     }
-    const body = await parseResponseBody(response);
-    if (!response.ok) {
-      const requestId = response.headers.get("x-request-id") ?? void 0;
-      const apiError = new GibworkApiError(
-        response.status,
-        body,
-        request.method,
-        request.path,
-        requestId
-      );
-      if (request.ambiguousSubmit && response.status >= 500) {
-        throw new GibworkAmbiguousSubmitError(
-          request.method,
-          request.path,
-          request.ambiguousSubmit,
-          { cause: apiError }
-        );
-      }
-      throw apiError;
-    }
-    return body;
   }
 };
 function normalizeBaseUrl(value) {
@@ -923,8 +1196,11 @@ exports.GibworkClient = GibworkClient;
 exports.GibworkConfigurationError = GibworkConfigurationError;
 exports.GibworkError = GibworkError;
 exports.GibworkNetworkError = GibworkNetworkError;
+exports.GibworkProtocolError = GibworkProtocolError;
 exports.GibworkRequestAbortedError = GibworkRequestAbortedError;
+exports.GibworkSubmissionOperationError = GibworkSubmissionOperationError;
 exports.GibworkTimeoutError = GibworkTimeoutError;
+exports.GibworkValidationError = GibworkValidationError;
 exports.createGibworkClient = createGibworkClient;
 exports.createKeypairSigner = createKeypairSigner;
 exports.keypairFromPrivateKey = keypairFromPrivateKey;