@osdk/osdk-docs-context

A public NPM package that provides structured access to OSDK TypeScript code examples organized by version, with template variations for different usage contexts.

Purpose

This package provides OSDK code examples in two formats:

Flat structure: Direct access when you know exact template names
Nested structure: Hierarchical organization with variations grouped under base templates

What are Template Variations?

Many OSDK templates have different code examples based on properties or conditions. For example:

derivedPropertyNumericExpression (base template)
- #isUnary variation - shows unary numeric operations
- ^isUnary variation - shows non-unary numeric operations

This allows you to see different code contexts for the same concept.

Installation

npm install @osdk/osdk-docs-context
# or
pnpm add @osdk/osdk-docs-context

Usage

Basic Example Access

import {
  NestedOsdkExamplesContext,
  OSDK_DOCS_CONTEXT,
} from "@osdk/osdk-docs-context";

// Get all available OSDK versions
const versions = NestedOsdkExamplesContext.getAvailableVersions();

// Get a simple template (no variations)
const example = NestedOsdkExamplesContext.getExample("2.4.0", [
  "loadGeotimeSeriesPointsSnippet",
]);

// Get a template variation
const variation = NestedOsdkExamplesContext.getExample("2.4.0", [
  "derivedPropertyNumericExpression",
  "#isUnary",
]);

Working with Template Variations

// Check if a template has variations
const hasVariations = NestedOsdkExamplesContext.hasVariations(
  "2.4.0",
  "derivedPropertyNumericExpression",
);

// Get all variations for a template
const variations = NestedOsdkExamplesContext.getVariations(
  "2.4.0",
  "derivedPropertyNumericExpression",
);
// Returns: ["#isUnary", "^isUnary"]

// Access specific variations
variations.forEach(variation => {
  const code = NestedOsdkExamplesContext.getExample("2.4.0", [
    "derivedPropertyNumericExpression",
    variation,
  ]);
  console.log(`${variation}:`, code?.code);
});

Search and Discovery

// Search examples across all versions
const results = NestedOsdkExamplesContext.searchExamples("numeric");

// Search within a specific version
const versionResults = NestedOsdkExamplesContext.searchExamples(
  "load",
  "2.4.0",
);

Version Compatibility

The package implements semantic version fallback - newer versions include examples from older compatible versions:

// 2.4.0 includes examples from 2.0.0, 2.1.0, and 2.4.0
const examples240 = NestedOsdkExamplesContext.getBaseExamplesForVersion(
  "2.4.0",
);

// 2.1.0 includes examples from 2.0.0 and 2.1.0 (but NOT 2.4.0)
const examples210 = NestedOsdkExamplesContext.getBaseExamplesForVersion(
  "2.1.0",
);

Data Structure

Each example includes:

filePath: Location of the source file
code: The actual TypeScript code
Version and variation metadata

{
  "2.4.0": {
    "examples": {
      "loadGeotimeSeriesPointsSnippet": {
        "filePath": "examples/typescript/2.4.0/loadGeotimeSeriesPointsSnippet.ts",
        "code": "// TypeScript code here..."
      },
      "derivedPropertyNumericExpression": {
        "#isUnary": {
          "filePath": "examples/typescript/2.4.0/derivedPropertyNumericExpression_#isUnary.ts",
          "code": "// Unary operation code..."
        },
        "^isUnary": {
          "filePath": "examples/typescript/2.4.0/derivedPropertyNumericExpression_^isUnary.ts",
          "code": "// Non-unary operation code..."
        }
      }
    }
  }
}

MCP Server Integration

This package is designed for MCP servers and external tools:

// Perfect for MCP servers - stable public API
import { NestedOsdkExamplesContext } from "@osdk/osdk-docs-context";

function getOsdkExamples(version: string, templateName?: string) {
  if (templateName) {
    return NestedOsdkExamplesContext.getExample(version, [templateName]);
  }
  return NestedOsdkExamplesContext.getExamplesWithVersionInfo(version);
}

Build

pnpm build

Generates ES modules, CommonJS, and TypeScript declarations in the build/ directory.