@gibwork/sdk 0.0.5 → 0.1.0

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`;
@@ -379,6 +622,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,
@@ -530,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);
@@ -675,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;
@@ -684,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,
@@ -704,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,
@@ -719,6 +1029,8 @@ var HttpTransport = class {
           { cause }
         );
       }
+      if (cause instanceof GibworkApiError || cause instanceof GibworkProtocolError)
+        throw cause;
       if (timedOut) {
         throw new GibworkTimeoutError(
           request.method,
@@ -733,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 }
@@ -741,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) {
@@ -904,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;