@olympex-io/olympex-sdk 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,107 @@
+# Getting Started
+
+This SDK is a thin GraphQL client over the Olympex backend. It signs requests **server-side**
+using `apiKey`, `apiSecret`, and `passphrase`.
+
+> **Server-side only** — do not use this SDK directly in browser bundles. See
+> `docs/authentication.md`.
+
+## Backend URL
+
+The SDK resolves the GraphQL endpoint from `OLYMPEX_BACKEND_URL` at call time. When unset,
+empty, or whitespace-only, it defaults to production (`https://back.olympex.io/graphql`).
+
+You may set either the backend origin or the full GraphQL path:
+
+| Deployment | Example `OLYMPEX_BACKEND_URL`                                                  |
+| ---------- | ------------------------------------------------------------------------------ |
+| Production | _(unset — uses default)_                                                       |
+| Staging    | `https://staging-back.olympex.io` or `https://staging-back.olympex.io/graphql` |
+| Local dev  | `http://localhost:4000` or `http://localhost:4000/graphql`                     |
+
+GraphQL requests use the resolved endpoint. REST onboarding POSTs to `{origin}/api/v1/accounts`
+(the SDK strips `/graphql` from the resolved endpoint when needed).
+
+## Minimal Node example
+
+```ts
+import { initialize } from '@olympex-io/olympex-sdk';
+
+const client = initialize({
+  apiKey: process.env.OLYMPEX_API_KEY!,
+  apiSecret: process.env.OLYMPEX_API_SECRET!,
+  passphrase: process.env.OLYMPEX_PASSPHRASE!,
+});
+
+console.log(client.getVersion());
+console.log(await client.supportChain(1));
+```
+
+For staging or local backends, set `OLYMPEX_BACKEND_URL` in your environment before calling
+`initialize` or `createAccount`.
+
+## Account onboarding
+
+`createAccount` is REST-based and does not require `initialize`:
+
+```ts
+import { createAccount } from '@olympex-io/olympex-sdk';
+
+const credentials = await createAccount({
+  name: 'My App',
+  password: process.env.OLYMPEX_ACCOUNT_PASSWORD!,
+});
+
+// credentials.apiKey    → OLYMPEX_API_KEY
+// credentials.secretKey → OLYMPEX_API_SECRET
+// password above        → OLYMPEX_PASSPHRASE
+```
+
+See `docs/authentication.md` for the full credential lifecycle.
+
+## Quote
+
+Fees are configured per request with `feeRecipient` and optional `feeBps`. These declare **integrator margin**; channel resolution and `platformFeeIntegrator` are backend-owned from signed auth. See [`fees.md`](./fees.md).
+
+```ts
+const quote = await client.quote({
+  mode: 'cross-chain',
+  params: {
+    fromChainId: 56,
+    toChainId: 137,
+    fromTokenAddress: '0x...',
+    toTokenAddress: '0x...',
+    amount: '1',
+    slippage: '0.5',
+  },
+  fees: {
+    feeBps: 15,
+    feeRecipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+  },
+});
+```
+
+## Swap
+
+```ts
+const swap = await client.swap({
+  mode: 'single-chain',
+  params: {
+    chainId: 1,
+    inTokenAddress: '0x...',
+    outTokenAddress: '0x...',
+    amount: '1',
+    slippage: '1',
+    gasPrice: '30',
+    account: '0x...',
+    aggregatorId: 'olympex',
+  },
+  fees: {
+    feeRecipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+  },
+});
+```
+
+Optional fee fields (`feeBps`, `feeRecipient`) can also be set once via
+`initialize({ defaultFees })`. Per-call `fees` override client defaults.
+See [docs/fees.md](./fees.md).

package/docs/logging.md

@@ -0,0 +1,85 @@
+# SDK logging
+
+The Olympex SDK is **silent by default**. No log output is produced unless you pass an `OlympexLogger` to `initialize({ logger })`.
+
+## OlympexLogger contract
+
+```typescript
+interface OlympexLogger {
+  log(level: LogLevel, message: string, metadata?: Record<string, unknown>): void;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+```
+
+- Compatible with pino, winston, or any adapter that exposes the same `log(level, message, metadata?)` signature.
+- Your implementation **must not throw** — a throwing logger can break SDK methods mid-flight.
+- All SDK-emitted `metadata` is passed through `redact()` before reaching your logger (api keys, tokens, secrets stripped).
+
+## createConsoleLogger
+
+Zero-dependency console adapter for quick local debugging:
+
+```typescript
+import { createConsoleLogger, initialize } from '@olympex-io/olympex-sdk';
+
+const client = initialize({
+  apiKey: process.env.OLYMPEX_API_KEY!,
+  logger: createConsoleLogger({ minLevel: 'info' }), // default minLevel is 'info'
+});
+```
+
+| Option     | Default  | Description                                                             |
+| ---------- | -------- | ----------------------------------------------------------------------- |
+| `minLevel` | `'info'` | Suppresses levels below this rank (`debug` < `info` < `warn` < `error`) |
+
+Use `minLevel: 'debug'` to see outgoing GraphQL request metadata in the console.
+
+## Stable log message strings
+
+Callers may grep or match on these strings. Treat them as part of the public log surface:
+
+| Level   | Message                                           |
+| ------- | ------------------------------------------------- |
+| `debug` | `Sending Olympex GraphQL request`                 |
+| `warn`  | `Olympex GraphQL response contains errors`        |
+| `error` | `Olympex GraphQL request failed with HTTP status` |
+| `error` | `Olympex GraphQL response was not valid JSON`     |
+| `error` | `Olympex GraphQL network failure`                 |
+| `info`  | `Olympex quote requested`                         |
+| `info`  | `Olympex swap requested`                          |
+
+Quote/swap `info` logs include only `mode` and chain id(s) — never amounts, routes, token addresses, or fee values.
+
+## pino adapter (5 lines)
+
+No peer dependency is bundled; wire pino yourself:
+
+```typescript
+import pino from 'pino';
+import type { OlympexLogger } from '@olympex-io/olympex-sdk';
+
+const pinoLogger = pino({ level: 'info' });
+const logger: OlympexLogger = {
+  log(level, message, metadata) {
+    pinoLogger[level](metadata ?? {}, message);
+  },
+};
+```
+
+## winston adapter (5 lines)
+
+```typescript
+import winston from 'winston';
+import type { OlympexLogger } from '@olympex-io/olympex-sdk';
+
+const winstonLogger = winston.createLogger({
+  level: 'info',
+  transports: [new winston.transports.Console()],
+});
+const logger: OlympexLogger = {
+  log(level, message, metadata) {
+    winstonLogger.log(level, message, metadata);
+  },
+};
+```

package/docs/methods/README.md

@@ -0,0 +1,25 @@
+# Public methods
+
+Method-level contracts for the partner SDK. Each page describes inputs, outputs, and error boundaries. The SDK is a thin GraphQL/REST client — it does not compute routes, fees, or calldata locally.
+
+| Method          | Doc                                           | Requires `initialize` |
+| --------------- | --------------------------------------------- | --------------------- |
+| `initialize`    | [`getting-started.md`](../getting-started.md) | —                     |
+| `createAccount` | [`create-account.md`](./create-account.md)    | No                    |
+| `quote`         | [`quote.md`](./quote.md)                      | Yes                   |
+| `swap`          | [`swap.md`](./swap.md)                        | Yes                   |
+| `supportChain`  | [`getting-started.md`](../getting-started.md) | Yes                   |
+| `txStatus`      | SDK JSDoc / backend schema                    | Yes                   |
+| `getVersion`    | README                                        | No                    |
+
+## GitBook export note
+
+Partner documentation lives in this repository under `docs/`. For GitBook or similar portals, sync these markdown files (plus `README.md`) rather than maintaining a separate copy. Suggested structure:
+
+- Getting started → `docs/getting-started.md`
+- Authentication → `docs/authentication.md`
+- Fees → `docs/fees.md`
+- Errors → `docs/errors.md`
+- Methods → `docs/methods/*`
+
+Until a GitBook space is provisioned, treat this folder as the source of truth.

package/docs/methods/create-account.md

@@ -0,0 +1,62 @@
+# `createAccount`
+
+Server-side REST bootstrap for partner credentials. Does **not** require `initialize`.
+
+## Signature
+
+```ts
+createAccount(input: CreateAccountInput, options?: CreateAccountOptions): Promise<CreateAccountResponse>
+```
+
+## REST contract
+
+```
+POST {origin}/api/v1/accounts
+Content-Type: application/json
+
+{ "name": "<app name>", "password": "<strong passphrase>" }
+```
+
+The SDK resolves `{origin}` from `OLYMPEX_BACKEND_URL` (see [`getting-started.md`](../getting-started.md#backend-url)).
+
+## Response
+
+| Field              | Maps to                                             |
+| ------------------ | --------------------------------------------------- |
+| `apiKey`           | `initialize({ apiKey })` / `OLYMPEX_API_KEY`        |
+| `secretKey`        | `initialize({ apiSecret })` / `OLYMPEX_API_SECRET`  |
+| `password` (input) | `initialize({ passphrase })` / `OLYMPEX_PASSPHRASE` |
+
+`secretKey` is returned **once** at creation. Store it immediately in a secret manager.
+
+## Example
+
+```ts
+import { createAccount, initialize } from '@olympex-io/olympex-sdk';
+
+const { apiKey, secretKey } = await createAccount({
+  name: 'My Integration',
+  password: process.env.OLYMPEX_ACCOUNT_PASSWORD!,
+});
+
+const client = initialize({
+  apiKey,
+  apiSecret: secretKey,
+  passphrase: process.env.OLYMPEX_ACCOUNT_PASSWORD!,
+});
+```
+
+Run bootstrap only from trusted server automation — never from browser code. See [`authentication.md`](../authentication.md).
+
+## Errors
+
+| Failure                             | Error class           |
+| ----------------------------------- | --------------------- |
+| Invalid input (empty name/password) | `OlympexConfigError`  |
+| HTTP/network failure                | `OlympexNetworkError` |
+| Unexpected response shape           | `OlympexNetworkError` |
+
+## Non-goals
+
+- Credential rotation API (contact Olympex ops)
+- Browser-accessible onboarding

package/docs/methods/quote.md

@@ -0,0 +1,84 @@
+# `quote`
+
+Returns a backend-computed quote for a single-chain or cross-chain swap. The SDK validates and forwards parameters; it does not calculate routes, amounts, or fees.
+
+## Signature
+
+```ts
+quote(input: QuoteRequest): Promise<QuoteResult>
+```
+
+Available on the object returned by `initialize`.
+
+## Modes
+
+| Mode           | GraphQL operation    | Key params                                                        |
+| -------------- | -------------------- | ----------------------------------------------------------------- |
+| `single-chain` | `getQuote`           | `chainId`, token addresses, `amount`, `slippage`, `gasPrice`      |
+| `cross-chain`  | `getCrossChainQuote` | `fromChainId`, `toChainId`, token addresses, `amount`, `slippage` |
+
+## Optional fees
+
+Pass `fees: { feeBps?, feeRecipient? }` to declare integrator margin for this call. Per-call `fees` override `initialize({ defaultFees })`. See [`fees.md`](../fees.md).
+
+## Example — single-chain
+
+```ts
+import { initialize } from '@olympex-io/olympex-sdk';
+
+const client = initialize({
+  apiKey: process.env.OLYMPEX_API_KEY!,
+  apiSecret: process.env.OLYMPEX_API_SECRET!,
+  passphrase: process.env.OLYMPEX_PASSPHRASE!,
+});
+
+const result = await client.quote({
+  mode: 'single-chain',
+  params: {
+    chainId: 1,
+    inTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
+    outTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    amount: '1',
+    slippage: '1',
+    gasPrice: '30',
+  },
+  fees: {
+    feeBps: 15,
+    feeRecipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+  },
+});
+
+console.log(result.mode, result.quote);
+```
+
+## Example — cross-chain
+
+```ts
+const result = await client.quote({
+  mode: 'cross-chain',
+  params: {
+    fromChainId: 56,
+    toChainId: 137,
+    fromTokenAddress: '0x...',
+    toTokenAddress: '0x...',
+    amount: '1',
+    slippage: '0.5',
+  },
+});
+```
+
+## Errors
+
+| Failure                            | Error class                            |
+| ---------------------------------- | -------------------------------------- |
+| Invalid `feeBps`, address, or mode | `OlympexConfigError` (no network call) |
+| Backend `success: false`           | `OlympexDomainError`                   |
+| GraphQL execution errors           | `OlympexGraphQLError`                  |
+| Network, timeout, 401/403          | `OlympexNetworkError`                  |
+
+See [`errors.md`](../errors.md).
+
+## Non-goals
+
+- Local route or price calculation
+- Channel detection or protocol fee selection

package/docs/methods/swap.md

@@ -0,0 +1,69 @@
+# `swap`
+
+Builds swap calldata and metadata from a backend quote path. The SDK validates and forwards parameters; execution happens on-chain via returned calldata.
+
+## Signature
+
+```ts
+swap(input: SwapRequest): Promise<SwapResult>
+```
+
+Available on the object returned by `initialize`.
+
+## Modes
+
+| Mode           | GraphQL operation   | Key params                                                                         |
+| -------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `single-chain` | `getQuoteSwap`      | `chainId`, tokens, `amount`, `slippage`, `gasPrice`, `account`, `aggregatorId`     |
+| `cross-chain`  | `getCrossChainSwap` | `fromChainId`, `toChainId`, tokens, `amount`, `slippage`, `account`, bridge fields |
+
+## Optional fees
+
+Same integrator margin fields as `quote`. See [`fees.md`](../fees.md).
+
+## Example — single-chain
+
+```ts
+import { initialize } from '@olympex-io/olympex-sdk';
+
+const client = initialize({
+  apiKey: process.env.OLYMPEX_API_KEY!,
+  apiSecret: process.env.OLYMPEX_API_SECRET!,
+  passphrase: process.env.OLYMPEX_PASSPHRASE!,
+});
+
+const result = await client.swap({
+  mode: 'single-chain',
+  params: {
+    chainId: 1,
+    inTokenAddress: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE',
+    outTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+    amount: '1',
+    slippage: '1',
+    gasPrice: '30',
+    account: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    aggregatorId: 'olympex',
+  },
+  fees: {
+    feeRecipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+  },
+});
+
+console.log(result.mode, result.swap);
+```
+
+## Errors
+
+| Failure                          | Error class           |
+| -------------------------------- | --------------------- |
+| Invalid fees, addresses, or mode | `OlympexConfigError`  |
+| Backend `success: false`         | `OlympexDomainError`  |
+| GraphQL errors                   | `OlympexGraphQLError` |
+| Network / auth failures          | `OlympexNetworkError` |
+
+See [`errors.md`](../errors.md).
+
+## Non-goals
+
+- Local calldata generation or fee math
+- Wallet signing (integrator signs and submits returned transactions)

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@olympex-io/olympex-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olympexio/olympex-sdk.git"
+  },
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for Olympex partner integrations.",
+  "license": "Apache-2.0",
+  "packageManager": "yarn@4.15.0",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": {
+        "import": "./dist/index.mjs",
+        "require": "./dist/index.js"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --exclude tests/packaging",
+    "test:packaging": "vitest run tests/packaging",
+    "test:coverage": "vitest run --coverage --exclude tests/packaging",
+    "lint:jsdoc": "node --experimental-strip-types scripts/validate-export-jsdoc.ts",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "prepack": "yarn build",
+    "debugging": "tsx ./scripts/sdk-instance.ts",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "olympex",
+    "sdk",
+    "graphql",
+    "web3",
+    "typescript"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "2.31.0",
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.7.5",
+    "@vitest/coverage-v8": "4.1.9",
+    "dotenv": "17.4.2",
+    "eslint": "10.4.1",
+    "eslint-plugin-jsdoc": "63.0.4",
+    "husky": "9.1.7",
+    "lint-staged": "17.0.7",
+    "prettier": "3.8.3",
+    "tsup": "8.5.1",
+    "tsx": "4.22.4",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.60.0",
+    "vitest": "4.1.9"
+  },
+  "dependencies": {
+    "ethers": "6.16.0"
+  }
+}