@gibwork/sdk 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this package will be documented here.
+
+## Unreleased
+
+- 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.
+- Add typed HTTP, timeout, cancellation, and ambiguous-submit errors.
+- Embed `https://sdk.gib.work` by default with a build-time API URL override.

package/README.md

@@ -0,0 +1,176 @@
+# Gibwork SDK
+
+TypeScript SDK for the wallet-authenticated Gibwork External API.
+
+It handles wallet addresses, nonces, timestamps, payload normalization,
+message signatures, HTTP requests, and Solana transaction signing for you.
+
+## Installation
+
+The package is currently private while its npm name and license are finalized.
+Once published:
+
+```bash
+npm install @gibwork/sdk
+```
+
+Requires Node.js 22 or newer.
+
+## Quick start
+
+Load your environment variables in the application, then pass the private key
+to the Node entry point. The SDK never loads `.env` implicitly.
+
+```dotenv
+SOLANA_PRIVATE_KEY=[1,2,3,...]
+```
+
+```ts
+import { createGibworkClient } from '@gibwork/sdk/node';
+
+const gibwork = createGibworkClient({
+  privateKey: process.env.SOLANA_PRIVATE_KEY!,
+});
+```
+
+The SDK uses the embedded `https://sdk.gib.work` API URL by default, so
+application users do not need to configure an API origin.
+
+`SOLANA_PRIVATE_KEY` may be a base58-encoded 32-byte seed or 64-byte secret
+key, or a JSON array containing 32 or 64 byte values.
+
+Applications using a wallet adapter or custom custody provider can inject a
+signer instead:
+
+```ts
+import { GibworkClient, type WalletSigner } from '@gibwork/sdk';
+
+declare const signer: WalletSigner;
+
+const gibwork = new GibworkClient({
+  signer,
+});
+```
+
+### API URL builds
+
+`https://sdk.gib.work` is embedded into normal package builds. SDK maintainers
+can produce an environment-specific build by setting `GIBWORK_SDK_API_URL`
+while building:
+
+```bash
+GIBWORK_SDK_API_URL=https://sdk-stage.gib.work npm run build
+```
+
+The selected URL is compiled into `dist`; installed applications do not need
+that environment variable. `DEFAULT_GIBWORK_API_URL` exposes the embedded
+value.
+
+For local tests or custom deployments, `baseUrl` remains an optional runtime
+override:
+
+```ts
+const gibwork = createGibworkClient({
+  privateKey: process.env.SOLANA_PRIVATE_KEY!,
+  baseUrl: 'http://localhost:3334',
+});
+```
+
+## Methods
+
+```ts
+const task = await gibwork.tasks.create({
+  title: 'Write an SDK guide',
+  content: '<p>Document the Gibwork SDK.</p>',
+  tags: ['Docs'],
+  payment: {
+    mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    amount: '25.00',
+  },
+  minSubmissionAmount: '5.00',
+});
+
+const tasks = await gibwork.tasks.list();
+const submissions = await gibwork.submissions.list(task.taskId);
+
+await gibwork.submissions.approve(task.taskId, submissionId, {
+  amount: '5.00',
+  rating: 5,
+});
+
+await gibwork.submissions.reject(
+  task.taskId,
+  submissionId,
+  'Please include the source files.',
+);
+
+const comments = await gibwork.submissions.comments.list(
+  task.taskId,
+  submissionId,
+);
+await gibwork.submissions.comments.create(
+  task.taskId,
+  submissionId,
+  'Thanks for the update.',
+);
+
+await gibwork.tasks.refund(task.taskId);
+```
+
+`tasks.create`, `tasks.refund`, and `submissions.approve` perform the complete
+prepare, sign, and submit sequence. Advanced callers can control the phases
+with:
+
+- `tasks.prepareCreate` and `tasks.submitCreate`
+- `tasks.prepareRefund` and `tasks.submitRefund`
+- `submissions.prepareApproval` and `submissions.submitApproval`
+- `signPreparedTransaction`
+
+All request methods accept an optional final `{ signal }` argument for
+cancellation. Set the default request timeout with `timeoutMs` when creating
+the client.
+
+## Errors
+
+API failures throw `GibworkApiError` with `status` and the parsed response
+`body`. 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.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+The package is intentionally marked `private` and `UNLICENSED` while its public
+API, npm ownership, and license are undecided. Those release gates must be
+resolved before the first npm publish.
+
+## Structure
+
+```text
+src/
+  auth/           Request normalization, hashing, nonces, and signatures
+  client/         Top-level SDK client and configuration
+  errors/         Typed SDK and API errors
+  resources/      Task and submission resource clients
+  signers/        Wallet signer contracts and opt-in adapters
+  transactions/   Prepare, sign, and submit orchestration
+  transport/      HTTP transport, response parsing, and retry policy
+  types/          Public request and response types
+tests/
+  integration/    Tests against a running External API
+  unit/           Isolated SDK behavior tests
+```
+
+## Private-key safety
+
+The SDK never transmits the private key, loads `.env` implicitly, or includes
+key material in its errors. Never expose the Node private-key entry point in a
+browser bundle. Browser consumers should provide a wallet-adapter-backed
+signer.