Add Coinbase SDK documentation and product guides

.github/dependabot.yml

@@ -12,16 +12,19 @@ updates:
       - dependency-name: bybit-api
       - dependency-name: binance
       - dependency-name: '@siebly/kraken-api'
+      - dependency-name: coinbase-api
     groups:
       sdk-releases:
         patterns:
           - '@siebly/hyperliquid-api'
           - bybit-api
           - binance
           - '@siebly/kraken-api'
+          - coinbase-api
     cooldown:
       exclude:
         - '@siebly/hyperliquid-api'
         - bybit-api
         - binance
         - '@siebly/kraken-api'
+        - coinbase-api

compatibility/adapters/coinbase.mjs

@@ -0,0 +1,25 @@
+export const operations = {
+  rest: 'CBAdvancedTradeClient.getPublicProduct()',
+  websocket: 'WebsocketClient.subscribe()',
+};
+export function client(sdk) {
+  return new sdk.CBAdvancedTradeClient({}, { timeout: 15000 });
+}
+export async function read(client) {
+  const ticker = await client.getPublicProduct({ product_id: 'BTC-USD' });
+  return ticker.price;
+}
+export function stream(sdk) {
+  return new sdk.WebsocketClient();
+}
+export const event = 'update';
+export function value(message) {
+  return message.channel === 'ticker' ? message.events?.flatMap(event => event.tickers || []).find(ticker => ticker.product_id === 'BTC-USD')?.price : undefined;
+}
+export async function subscribe(ws) {
+  ws.subscribe({ topic: 'ticker', payload: { product_ids: ['BTC-USD'] } }, 'advTradeMarketData');
+}
+export const typeExample = `import { CBAdvancedTradeClient, WebsocketClient } from 'coinbase-api';
+new CBAdvancedTradeClient().getPublicProduct({ product_id: 'BTC-USD' });
+new WebsocketClient().closeAll();
+`;

compatibility/browser-config/coinbase.mjs

@@ -0,0 +1,34 @@
+import { fileURLToPath } from 'node:url';
+
+// Public market data only. Coinbase's JWT helper imports Node crypto eagerly.
+// Keep credentialed calls on a Node.js server rather than bundling private keys.
+const publicAuth = '\0coinbase-public-auth';
+const sdkRoot = fileURLToPath(new URL('./node_modules/coinbase-api/', import.meta.url));
+export default {
+  // Keep SDK modules in Vite's transform pipeline so the JWT replacement also
+  // applies during development. Prebundle its CommonJS browser dependencies.
+  optimizeDeps: {
+    exclude: ['coinbase-api'],
+    include: ['events', 'coinbase-api > isomorphic-ws'],
+  },
+  resolve: {
+    alias: {
+      events: fileURLToPath(new URL('./node_modules/events/events.js', import.meta.url)),
+    },
+  },
+  plugins: [{
+    name: 'coinbase-public-market-data',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      if (source.endsWith('/jwtNode.js') && importer?.startsWith(sdkRoot)) {
+        return publicAuth;
+      }
+    },
+    load(id) {
+      if (id === publicAuth) {
+        return `export function signJWT() { throw new Error('JWT signing is server-only in this public market-data starter.'); }
+export const signWSJWT = signJWT;`;
+      }
+    },
+  }],
+};

compatibility/browser.mjs

@@ -85,7 +85,7 @@ document.getElementById('status').textContent=response.ok?'Complete. Results sav
     await writeFile(path.join(evidence,`${evidenceName}.json`),JSON.stringify({report,warnings,profile},null,2));
     const passed=completeBrowserResult(report.checks);
     const version=/Chrome\/([\d.]+)/.exec(report.userAgent)?.[1];
-    const description=profile==='vite'?'The default Vite consumer':profile==='configured'?'The Vite consumer with an events polyfill'+(id==='binance'?' and the SDK browser-signing alias':''):'The standalone browser bundle shipped in this npm package';
+    const description=profile==='vite'?'The default Vite consumer':profile==='configured'?'The Vite consumer with an events polyfill'+(id==='binance'?' and the SDK browser-signing alias':id==='coinbase'?' and public-only JWT rejection':''):'The standalone browser bundle shipped in this npm package';
     return {status:passed?'passed':'failed',runtimeVersion:version?`Chromium ${version}`:report.userAgent,checks:[{id:'bundle',status:'passed'},...report.checks],reason:passed?`${description} passed execution checks in the browser shown here, against the live exchange REST and WebSocket APIs.`:`${description} failed browser execution checks. See the observed failures below.`,userAgent:report.userAgent,secureContext:report.secureContext,warnings,profile};
   }finally{
     clearTimeout(timer);

compatibility/native-config/coinbase-public-auth.cjs

@@ -0,0 +1,5 @@
+// This consumer is for public data only. Keep API credentials on your server.
+function signJWT() {
+  throw new Error('JWT signing is server-only in this public market-data starter.');
+}
+module.exports = { signJWT, signWSJWT: signJWT };

compatibility/native-config/coinbase.metro.cjs

@@ -0,0 +1,26 @@
+const path = require('node:path');
+
+module.exports = function configureSdkMetro(config, projectRoot) {
+  const aliases = {
+    https: require.resolve('https-browserify', { paths: [projectRoot] }),
+    http: require.resolve('stream-http', { paths: [projectRoot] }),
+    url: require.resolve('url/', { paths: [projectRoot] }),
+  };
+  const previousResolveRequest = config.resolver.resolveRequest;
+
+  config.resolver.resolveRequest = (context, moduleName, platform) => {
+    // Replace only Coinbase's Node-only JWT implementation for public consumers.
+    if (moduleName.endsWith('/jwtNode.js') &&
+        context.originModulePath.startsWith(path.join(projectRoot, 'node_modules/coinbase-api') + path.sep)) {
+      return { type: 'sourceFile', filePath: path.join(projectRoot, 'coinbase-public-auth.cjs') };
+    }
+    if (aliases[moduleName]) {
+      return { type: 'sourceFile', filePath: aliases[moduleName] };
+    }
+
+    const resolveRequest = previousResolveRequest || context.resolveRequest;
+    return resolveRequest(context, moduleName, platform);
+  };
+
+  return config;
+};

compatibility/native-config/recipe.mjs

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 
 export function nativeMetroConfig(id) {
-  const filename = { bybit: 'bybit.metro.cjs', binance: 'metro.cjs', kraken: 'kraken.metro.cjs' }[id];
+  const filename = { bybit: 'bybit.metro.cjs', binance: 'metro.cjs', kraken: 'kraken.metro.cjs', coinbase: 'coinbase.metro.cjs' }[id];
   if (!filename) {
     throw new Error(`No Metro polyfill recipe for ${id}.`);
   }

compatibility/native.mjs

@@ -38,6 +38,7 @@ export async function nativeCheck({id,consumer,evidence,env,packageName,packageV
     const dependencies=JSON.parse(await readFile(path.join(root,'compatibility/native-config/dependencies.json')));
     await npm(['install','--ignore-scripts','--save-exact',...Object.entries(dependencies).map(([name,version])=>`${name}@${version}`)],{cwd:consumer,env,timeout:120000,log:path.join(evidence,`${evidenceId}-polyfills-install.log`)});
     await writeFile(path.join(consumer,'siebly-sdk.metro.cjs'),await nativeMetroConfig(id));
+    if(id==='coinbase') await writeFile(path.join(consumer,'coinbase-public-auth.cjs'),await readFile(path.join(root,'compatibility/native-config/coinbase-public-auth.cjs')));
     result.consumerDependencies=dependencies;
   }
   const pkg=JSON.parse(await readFile(path.join(consumer,'package.json')));pkg.main='index.js';

releases/package.json

@@ -5,6 +5,7 @@
     "@siebly/hyperliquid-api": "1.0.3",
     "bybit-api": "4.8.5",
     "binance": "3.6.12",
-    "@siebly/kraken-api": "1.1.10"
+    "@siebly/kraken-api": "1.1.10",
+    "coinbase-api": "1.3.1"
   }
 }

scripts/check-public.mjs

@@ -20,7 +20,7 @@ export async function checkPublic(directory) {
     const stat = await lstat(filename);
     if (stat.isDirectory()) continue;
     if (stat.isFile() && path.extname(relative) === '.gz') {
-      const match = /^(hyperliquid|bybit|binance|kraken)\/starters\/(node|typescript|react|bun|deno|vite|next|expo)\.tar\.gz$/.exec(parts.join('/'));
+      const match = /^(hyperliquid|bybit|binance|kraken|coinbase)\/starters\/(node|typescript|react|bun|deno|vite|next|expo)\.tar\.gz$/.exec(parts.join('/'));
       if (!match || stat.size > 131072) throw new Error(`Unexpected public archive: ${relative}`);
       const sdk = (await import(`../sdks/${match[1]}/sdk.config.mjs`)).default;
       await checkStarter(filename, await environmentFiles(match[1], sdk, match[2]));

scripts/context.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { readFile } from 'node:fs/promises';
 
 export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-export const ids = ['hyperliquid', 'bybit', 'binance', 'kraken'];
+export const ids = ['hyperliquid', 'bybit', 'binance', 'kraken', 'coinbase'];
 
 export async function context(id) {
   if (!ids.includes(id)) throw new Error(`Unknown SDK: ${id}. Choose ${ids.join(', ')}.`);

scripts/environment-guides.mjs

@@ -10,6 +10,7 @@ export function codeBlock(filename, content) {
 
 const command = value => `\`\`\`sh\n${value}\n\`\`\``;
 const purposes = {
+  'coinbase-public-auth.cjs': 'Reject JWT signing in this public-data consumer. Keep credentialed API calls on a Node.js server.',
   'package.json': 'Declare the SDK dependency and the commands used by this project.',
   'tsconfig.json': 'Enable strict type checking and compile the TypeScript programs into `dist/`.',
   'deno.json': 'Tell Deno to install npm dependencies locally and define the price and stream tasks.',
@@ -90,10 +91,17 @@ export function guideFields(id, sdk, environment, files) {
         ? ['package.json', 'install', 'vite.config.js', 'main.js', 'index.html']
         : environment === 'next'
           ? ['package.json', 'install', 'app/layout.js', 'app/api/price/route.js', 'app/page.js']
-          : ['package.json', 'app.json', 'install', 'siebly-sdk.metro.cjs', 'metro.config.cjs', 'App.js', 'index.js'];
+          : ['package.json', 'app.json', 'install', 'coinbase-public-auth.cjs', 'siebly-sdk.metro.cjs', 'metro.config.cjs', 'App.js', 'index.js'];
     app = orderedSteps(names, files);
   }
 
+  if (id === 'coinbase') {
+    streamFiles = streamFiles
+      .replace('it closes the client after the first price or a failure.', 'it streams prices until you press Ctrl+C. Exceptions and reconnections are logged without stopping the client.')
+      .replace('when you want a live update. Its promise resolves to a price string and its `finally` block closes the client.', 'to stream prices until Ctrl+C. Signal handlers close the client; exceptions and reconnections are logged without stopping it.')
+      .replace('to receive one WebSocket price and close the connection.', 'to stream WebSocket prices until Ctrl+C.');
+  }
+
   return {
     PROJECT_SETUP: setup,
     CONFIG_FILES: config,

scripts/environments.mjs

@@ -154,6 +154,9 @@ export async function environmentFiles(id, sdk, environment) {
     if (id !== 'hyperliquid') {
       Object.assign(pkg.dependencies, JSON.parse(await source('compatibility/native-config/dependencies.json')));
       files.set('siebly-sdk.metro.cjs', await nativeMetroConfig(id));
+      if (id === 'coinbase') {
+        files.set('coinbase-public-auth.cjs', await source('compatibility/native-config/coinbase-public-auth.cjs'));
+      }
       files.set('metro.config.cjs', "const { getDefaultConfig } = require('expo/metro-config');\nconst configureSdkMetro = require('./siebly-sdk.metro.cjs');\n\nconst config = getDefaultConfig(__dirname);\n\nmodule.exports = configureSdkMetro(config, __dirname);\n");
     }
   }
@@ -237,6 +240,21 @@ export async function generateEnvironments(ctx) {
       if (!(key in substitutions)) throw new Error(`Missing environment template field: ${key}`);
       return substitutions[key];
     });
+    if (ctx.id === 'coinbase') {
+      rendered = rendered
+        .replace('The script prints the first update, closes its WebSocket and exits.', 'The script keeps streaming until Ctrl+C. Exceptions and reconnections are logged; signal handlers close the client.')
+        .replace('The script receives one update, closes the client in `finally` and exits.', 'The script keeps streaming until Ctrl+C. Exceptions and reconnections are logged; signal handlers close the client.');
+      rendered = rendered
+        .replace('A failed request or no update within 30 seconds needs a network check.', 'A failed request or a stream without updates needs a network check.')
+        .replace('If a request fails or no update arrives within 30 seconds,', 'If a request fails or no stream updates arrive,');
+      const note = browser || environment === 'expo'
+        ? 'This is a public-market-data recipe only: the supplied configuration disables the SDK’s Node-only JWT signing helper. Keep the configuration and, for Expo, `coinbase-public-auth.cjs`. Run authenticated calls on your Node.js server. Browser REST access also depends on Coinbase CORS policy.'
+        : 'This project uses Advanced Trade public market data. Keep credentialed account and trading calls in a server-side application.';
+      rendered = rendered
+        .replace('## Create the project', note + '\n\n## Create the project')
+        .replace('See Runtime compatibility for recorded verification of this configuration.', 'Keep the public-auth helper alongside the Metro configuration.')
+        .replaceAll('[Runtime compatibility](/compatibility) for tested versions', '[Runtime setup](/compatibility) for the other project recipes');
+    }
     if (ctx.id === 'kraken') {
       const note = browser
         ? 'The public GET client below omits two SDK request headers that trigger a failing Kraken CORS preflight. This is an example-specific setup for public reads, not general browser REST support. See [Browser REST and CORS](/guides/troubleshooting#browser-rest-and-cors) for the limitation and a server-side alternative.'

scripts/generate.mjs

@@ -1,6 +1,6 @@
 import { readFile, writeFile, mkdir, readdir, cp, rm } from 'node:fs/promises';
 import path from 'node:path';
-import { Application, Comment, CommentTag, ReflectionKind } from 'typedoc';
+import { Application, Comment, CommentTag, Converter, ReflectionKind } from 'typedoc';
 import { context, root, catalogue } from './context.mjs';
 import { compilerConfig } from './compiler.mjs';
 import { generateCompatibility } from '../compatibility/report.mjs';
@@ -12,9 +12,18 @@ await rm(projectRoot, { recursive: true, force: true });
 await mkdir(projectRoot, { recursive: true });
 await cp(path.join(ctx.content, 'docs'), ctx.docs, { recursive: true });
 await copySharedContent(root, ctx.docs);
+if (sdk.compatibilityPage === 'authored') {
+  // Reuse the shared setup table while pointing to this SDK's setup-only page.
+  const setupFragment = path.join(ctx.docs, '.vitepress/shared/getting-started/environments.md');
+  const content = await readFile(setupFragment, 'utf8');
+  await writeFile(setupFragment, content.replace(
+    'See [Runtime compatibility](/compatibility) for tested versions, required configuration and check scope.',
+    'See [Runtime setup](/compatibility) for project recipes and required configuration.',
+  ));
+}
 await cp(path.join(ctx.content, 'examples'), path.join(projectRoot, 'examples'), { recursive: true });
 await cp(path.join(root, 'shared/public'), path.join(ctx.docs, 'public'), { recursive: true });
-await generateCompatibility(ctx, root);
+if (sdk.compatibilityPage !== 'authored') await generateCompatibility(ctx, root);
 await generateEnvironments(ctx);
 
 const pkg = JSON.parse(await readFile(path.join(sdkRoot, 'package.json'), 'utf8'));
@@ -50,10 +59,24 @@ const app = await Application.bootstrapWithPlugins({
   typeAliasPropertiesFormat: 'table',
   validation: { notExported: true, invalidLink: true, notDocumented: false },
 });
+// Filter the documentation model before TypeDoc builds its groups and categories.
+app.converter.on(Converter.EVENT_RESOLVE_BEGIN, ({ project }) => {
+  for (const reflection of Object.values(project.reflections)) {
+    if (reflection.kind === ReflectionKind.Property && sdk.referenceExcludeProperties?.includes(reflection.name)) {
+      project.removeReflection(reflection);
+    }
+  }
+});
 const project = await app.convert();
 if (!project || app.logger.hasErrors()) throw new Error('TypeDoc conversion failed');
 
 // Enrich the documentation model, never the SDK or generated Markdown.
+for (const [name, description] of Object.entries(sdk.referenceDescriptions || {})) {
+  const reflection = project.getChildByName(name.split('.'));
+  if (!reflection) throw new Error(`Missing documented export: ${name}`);
+  reflection.comment = new Comment([{ kind: 'text', text: description }]);
+}
+
 // Exact member checks make renamed or removed methods fail the docs build.
 for (const help of sdk.referenceHelp || []) {
   const client = project.children.find((child) => child.name === help.client);

scripts/release-manifest.mjs

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 
 export const releaseManifestPath = 'releases/package.json';
-export const sdkPackages = ['@siebly/hyperliquid-api', 'bybit-api', 'binance', '@siebly/kraken-api'];
+export const sdkPackages = ['@siebly/hyperliquid-api', 'bybit-api', 'binance', '@siebly/kraken-api', 'coinbase-api'];
 export const stableVersion = (version) => typeof version === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version);
 
 export function releaseVersions(manifest) {

scripts/release-refresh.test.mjs

@@ -4,7 +4,7 @@ import { refreshReleases, updatedManifest, validateRefreshBranch, approveAndMerg
 import { requireMainDispatch, repository, refreshBranch, createGitHubApi } from './github-automation.mjs';
 
 const base = 'a'.repeat(40), proposal = 'b'.repeat(40), newer = 'c'.repeat(40);
-const manifest = (hl = '1.0.1') => ({ name: 'siebly-sdk-release-inputs', private: true, dependencies: { '@siebly/hyperliquid-api': hl, 'bybit-api': '4.8.4', binance: '3.6.11', '@siebly/kraken-api': '1.1.10' } });
+const manifest = (hl = '1.0.1') => ({ name: 'siebly-sdk-release-inputs', private: true, dependencies: { '@siebly/hyperliquid-api': hl, 'bybit-api': '4.8.4', binance: '3.6.11', '@siebly/kraken-api': '1.1.10', 'coinbase-api': '1.3.1' } });
 const pr = (head = proposal) => ({ state: 'open', number: 7, html_url: `https://github.com/${repository}/pull/7`, user: { login: 'github-actions[bot]', type: 'Bot' }, head: { sha: head, ref: refreshBranch, repo: { full_name: repository } }, base: { ref: 'main', repo: { full_name: repository } } });
 const comparison = () => ({ merge_base_commit: { sha: base }, total_commits: 1, files: [{ filename: 'releases/package.json', status: 'modified' }], commits: [{ author: { login: 'github-actions[bot]' } }] });
 

scripts/release-update.test.mjs

@@ -5,7 +5,7 @@ import { refreshBranch } from './github-automation.mjs';
 import { readReleaseVersions, releaseVersions, validateReleaseUpdate } from './release-manifest.mjs';
 
 const main = 'a'.repeat(40), head = 'b'.repeat(40);
-const manifest = () => ({ name: 'siebly-sdk-release-inputs', private: true, dependencies: { '@siebly/hyperliquid-api': '1.0.1', 'bybit-api': '4.8.4', binance: '3.6.11', '@siebly/kraken-api': '1.1.10' } });
+const manifest = () => ({ name: 'siebly-sdk-release-inputs', private: true, dependencies: { '@siebly/hyperliquid-api': '1.0.1', 'bybit-api': '4.8.4', binance: '3.6.11', '@siebly/kraken-api': '1.1.10', 'coinbase-api': '1.3.1' } });
 function candidate() {
   const before = manifest(), after = manifest();
   after.dependencies['bybit-api'] = '4.8.5';
@@ -18,7 +18,7 @@ function candidate() {
 }
 
 test('the committed manifest is the exact configured-package build input', async () => {
-  assert.deepEqual(Object.keys(await readReleaseVersions()).sort(), ['@siebly/hyperliquid-api', '@siebly/kraken-api', 'binance', 'bybit-api']);
+  assert.deepEqual(Object.keys(await readReleaseVersions()).sort(), ['@siebly/hyperliquid-api', '@siebly/kraken-api', 'binance', 'bybit-api', 'coinbase-api']);
   for (const version of ['latest', '^4.8.5', '4.8.5-beta.1', '04.8.5']) {
     const value = manifest(); value.dependencies['bybit-api'] = version;
     assert.throws(() => releaseVersions(value));