@gibwork/sdk 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this package will be documented here.
 
 ## Unreleased
 
+- Add cross-creator task discovery with `tasks.listAvailable`.
+- Add paid submission creation, prepare/submit methods, and intent status reads.
+- Preserve idempotency and payment recovery context without automatic retries.
+- Validate submission inputs and intent responses, and expose `Retry-After`.
+- Keep timeouts, cancellation, and ambiguous-submit handling active through response body reads.
+- Add thirteen API signing vectors, participation/recovery tests, and a persisted stage example.
+
 - Add the typed Gibwork client with complete External API route coverage.
 - Add high-level task creation, refund, and submission approval workflows.
 - Add injected-wallet and Node private-key signer support.

package/README.md

@@ -120,16 +120,100 @@ All request methods accept an optional final `{ signal }` argument for
 cancellation. Set the default request timeout with `timeoutMs` when creating
 the client.
 
+## Discover tasks and submit work
+
+```ts
+const available = await gibwork.tasks.listAvailable({ page: 1, limit: 15 });
+
+// Persist the key and exact input before sending. Supply your own UUIDv4.
+const input = {
+  content: '<p>Completed work: https://example.com/work</p>',
+  idempotencyKey: savedIdempotencyKey,
+};
+const intent = await gibwork.submissions.create(taskId, input);
+
+if (intent.status === 'submitted') {
+  const current = await gibwork.submissions.getIntent(taskId, intent.intentId);
+}
+```
+
+Discovery is free and wallet-authenticated across creators; `tasks.list` lists
+created tasks. Discovery accepts only `page` and `limit` (defaults 1/15, maximum
+limit 100). Results show eligibility requirements, not a guarantee that your
+wallet can submit. `asset.amount` and `minSubmissionAmount` are strings in base
+units; the asset amount is the original reward pool, not remaining funds.
+
+Submitting work requires an active platform wallet, eligibility, and currently
+**0.15 USDC**. Network costs are sponsored. Read the returned `fee` for amounts.
+Optional `referral` and `mediaIds` are supported; media must already be uploaded
+and owned by the caller. The SDK preserves submission content/referral exactly
+when signing, including whitespace and HTML.
+
+For separate phases use:
+
+- `submissions.prepareCreate(taskId, input)`
+- `signPreparedTransaction(prepared.serializedTransaction, signer)`
+- `submissions.submitCreate(taskId, intentId, { paymentAttemptId, signedTransaction })`
+- `submissions.getIntent(taskId, intentId)`
+
+Prepare can return an existing intent without a transaction. `submissions.create`
+signs only a pending intent with a transaction and returns the state after one
+submit; it does not poll or retry automatically.
+
+| State                | Meaning and recovery                                                                   |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `pending`            | Not submitted. Retry prepare with the original input/key to obtain the transaction.    |
+| `submitted`          | Unresolved. Read the same intent later.                                                |
+| `fulfilled`          | Fee confirmed and submission created.                                                  |
+| `failed` / `expired` | Resolve the attempt before explicitly choosing a new key.                              |
+| `requires_review`    | Fee paid; operator attention required. Retain the intent ID/hash and do not pay again. |
+
+Only `fulfilled` confirms creation. `taskSubmissionId` is allocated in advance;
+its presence and HTTP 200 alone do not prove success. Intent status does not
+report subsequent creator review/payout, and existing creator submission reads
+have not been extended to participants.
+
+After an interrupted prepare, reuse the exact input/key with the same wallet
+and environment. After an uncertain submit, use `getIntent` with the original
+wallet, including after wallet replacement. Each call generates fresh auth.
+The same key still returns the original intent after failure/expiry. A 409 error
+may contain an existing intent ID in its structured body.
+
+The upstream wallet limits are discovery 30/minute, prepare 2/minute, submit
+5/minute, and status 60/minute. Respect `GibworkApiError.retryAfter` (seconds or an
+HTTP date) before another request; it is optional. The
+[stage example](examples/create-submission.mjs) persists recovery data before
+payment and uses explicit status reads on later invocations:
+
+```bash
+npm run build
+node --env-file=.env examples/create-submission.mjs work.json recovery.json
+```
+
+`work.json` contains `{ "taskId": "UUID", "input": { "content": "...",
+"idempotencyKey": "UUIDv4" } }`. This example may charge the stage participation
+fee. Once it records an intent, rerunning only reads status. No media upload or
+operator resolution endpoint is provided by this SDK.
+
 ## Errors
 
 API failures throw `GibworkApiError` with `status` and the parsed response
-`body`. Network failures and timeouts use typed SDK errors.
+`body`, plus optional `requestId` and raw `retryAfter`. Network failures and timeouts use typed SDK errors.
 
 Transaction submits are never retried automatically. If the network or server
 fails while submitting, the SDK throws `GibworkAmbiguousSubmitError` with safe
 task, submission, and intent identifiers. Do not resubmit the same intent
 blindly.
 
+`GibworkValidationError` reports invalid discovery/submission input before a
+request. `GibworkProtocolError` reports an unusable intent response. The
+`submissions.create` convenience method wraps non-ambiguous failures in
+`GibworkSubmissionOperationError`: `context` retains the phase, original
+idempotency key, wallet/environment/API location, and intent identifiers when
+known; `cause` retains the original typed error. Ambiguous payments remain
+`GibworkAmbiguousSubmitError` with enriched context. A wallet rejection or
+cancellation before dispatch is not classified as a broadcast payment.
+
 ## Development
 
 ```bash

package/dist/{chunk-BNAVP5XZ.js → chunk-HJ5D5SOE.js}

@@ -14,19 +14,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 {
@@ -71,6 +73,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.defaults.allowedTags.concat(["img"]),
   allowedAttributes: {
@@ -225,6 +272,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(),
@@ -261,6 +344,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(
@@ -350,6 +457,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`;
@@ -369,6 +612,25 @@ var SubmissionsResource = class {
       ...options ? { options } : {}
     });
   }
+  async get(taskId, submissionId, options) {
+    const path = `/v2/int/tasks/${encodeURIComponent(taskId)}/submissions/${encodeURIComponent(submissionId)}`;
+    const headers = await createWalletAuthHeaders(this.signer, {
+      operation: "gibwork:view-task-submission",
+      method: "GET",
+      path,
+      resourceFields: [
+        ["taskId", taskId],
+        ["taskSubmissionId", submissionId]
+      ],
+      hash: ["queryHash", sha256Json({})]
+    });
+    return this.transport.request({
+      method: "GET",
+      path,
+      headers,
+      ...options ? { options } : {}
+    });
+  }
   async approve(taskId, submissionId, input, options) {
     const prepared = await this.prepareApproval(
       taskId,
@@ -520,6 +782,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);
@@ -665,6 +944,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;
@@ -674,12 +963,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,
@@ -694,13 +977,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,
@@ -709,6 +1019,8 @@ var HttpTransport = class {
           { cause }
         );
       }
+      if (cause instanceof GibworkApiError || cause instanceof GibworkProtocolError)
+        throw cause;
       if (timedOut) {
         throw new GibworkTimeoutError(
           request.method,
@@ -723,7 +1035,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 }
@@ -731,28 +1043,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) {
@@ -811,6 +1103,6 @@ function assertSigner(signer) {
   }
 }
 
-export { DEFAULT_GIBWORK_API_URL, GibworkAmbiguousSubmitError, GibworkApiError, GibworkClient, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkRequestAbortedError, GibworkTimeoutError, signPreparedTransaction };
-//# sourceMappingURL=chunk-BNAVP5XZ.js.map
-//# sourceMappingURL=chunk-BNAVP5XZ.js.map
+export { DEFAULT_GIBWORK_API_URL, GibworkAmbiguousSubmitError, GibworkApiError, GibworkClient, GibworkConfigurationError, GibworkError, GibworkNetworkError, GibworkProtocolError, GibworkRequestAbortedError, GibworkSubmissionOperationError, GibworkTimeoutError, GibworkValidationError, signPreparedTransaction };
+//# sourceMappingURL=chunk-HJ5D5SOE.js.map
+//# sourceMappingURL=chunk-HJ5D5SOE.js.map