@framers/openstrand-sdk

Installation

npm install @framers/openstrand-sdk
# or
yarn add @framers/openstrand-sdk
# or
pnpm add @framers/openstrand-sdk

Quick Start

import { OpenStrandSDK } from '@framers/openstrand-sdk';

const sdk = new OpenStrandSDK({
  apiUrl: process.env.OPENSTRAND_API_URL ?? 'http://localhost:8000',
});

// Authenticate (local mode)
const { token } = await sdk.auth.login({
  username: 'demo',
  password: 'Demo123!',
});

sdk.setToken(token);

// Create a strand
const strand = await sdk.strands.create({
  type: 'document',
  title: 'Knowledge Graph Notes',
  content: { markdown: '# Connections' },
  tags: ['knowledge', 'graph'],
});

console.info('strand-id', strand.id);

Features

• TypeSafe – generated TypeScript definitions line up with backend validation.
• Isomorphic – works in Node, browsers, and serverless runtimes.
• Configurable – retry/backoff, custom headers, and request hooks.
• Error-aware – throws descriptive error classes (AuthenticationError, ValidationError, etc.).
• Tree-shakeable – imports only what you need.

Configuration Options

const sdk = new OpenStrandSDK({
  apiUrl: 'http://localhost:8000',
  token: process.env.OPENSTRAND_TOKEN, // optional
  timeout: 30_000,
  retry: {
    enabled: true,
    maxRetries: 3,
    retryDelay: 1_000,
  },
  headers: {
    'X-Client': 'openstrand-cli',
  },
});

apiUrl is required. All other fields are optional.

Error Handling

import { AuthenticationError, NetworkError } from '@framers/openstrand-sdk';

try {
  await sdk.auth.login({ username: 'demo', password: 'wrong-pass' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof NetworkError) {
    console.error('Network issue:', error.cause);
  } else {
    console.error('Unexpected error', error);
  }
}

All API methods throw typed errors, making it easy to provide user-friendly messages.

Browser Usage

<script type="module">
  import { OpenStrandSDK } from 'https://cdn.jsdelivr.net/npm/@framers/openstrand-sdk/+esm';

  const sdk = new OpenStrandClient({
    apiUrl: 'https://api.openstrand.ai',
  });

  // ...
</script>

API Docs (TypeDoc)

Generate HTML docs from TSDoc comments:

npm install
npm run docs
# output: packages/openstrand-sdk/docs/

Links

• Repository: https://github.com/framersai/openstrand-monorepo
• Issues: https://github.com/framersai/openstrand-monorepo/issues
• Documentation: https://github.com/framersai/openstrand-monorepo/tree/master/docs