Shim SDK

TypeScript SDK for Shim. Intercept malformed JSON from LLMs. Repair it. Return valid data.

Installation

npm install shim-sdk

Quick Start

import { ShimClient } from 'shim-sdk';

const shim = new ShimClient({
  apiKey: 'sk_your_api_key'
});

// Batch repair
const result = await shim.repair({
  raw_output: '{"name": "John", "age": 30'
});

console.log(result.repaired); // { name: "John", age: 30 }
console.log(result.metadata.confidence); // "high"

API Reference

`new ShimClient(config)`

Create a new Shim client.

Parameters:

config.apiKey (string, required): Your Shim API key
config.baseUrl (string, optional): Custom API base URL (default: https://api.shim.so)

Example:

const shim = new ShimClient({
  apiKey: process.env.SHIM_API_KEY
});

`client.repair(request)`

Batch repair: Fix malformed JSON in one request.

Parameters:

request.raw_output (string, required): The malformed JSON string
request.schema (JSONSchema, optional): JSON Schema for validation
request.mode ('strict' | 'lenient', optional): Repair mode (default: 'strict')

Returns: Promise<RepairResponse>

Example:

const result = await shim.repair({
  raw_output: '{"name": "John", "age": "30"',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  }
});

if (result.success) {
  console.log(result.repaired); // { name: "John", age: 30 }
  console.log(result.metadata.confidence); // "high"
}

`client.stream.start(options)`

Start a new streaming session.

Parameters:

options.schema (JSONSchema, optional): JSON Schema for validation
options.mode ('strict' | 'lenient', optional): Repair mode

Returns: Promise<{ session_id: string; expires_at: number }>

Example:

const session = await shim.stream.start({
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' }
    }
  }
});

console.log(session.session_id); // "sess_abc123"

`client.stream.push(request)`

Push a chunk to an active streaming session.

Parameters:

request.session_id (string, required): Session ID from stream.start()
request.chunk (string, required): Chunk of JSON to process

Returns: Promise<{ state: StreamingState }>

Example:

const result = await shim.stream.push({
  session_id: session.session_id,
  chunk: '{"name": "Jo'
});

console.log(result.state.structurally_complete); // false
console.log(result.state.buffered); // '{"name": "Jo'

`client.stream.finalize(request)`

Finalize a streaming session and get the repaired result.

Parameters:

request.session_id (string, required): Session ID from stream.start()

Returns: Promise<RepairResponse>

Example:

const result = await shim.stream.finalize({
  session_id: session.session_id
});

console.log(result.repaired); // { name: "John" }

Streaming Example

import { ShimClient } from 'shim-sdk';

const shim = new ShimClient({
  apiKey: process.env.SHIM_API_KEY
});

// Start session
const session = await shim.stream.start();

// Push chunks as they arrive from LLM
await shim.stream.push({
  session_id: session.session_id,
  chunk: '{"name": "Jo'
});

await shim.stream.push({
  session_id: session.session_id,
  chunk: 'hn", "age": 30'
});

// Finalize when stream is complete
const result = await shim.stream.finalize({
  session_id: session.session_id
});

console.log(result.repaired); // { name: "John", age: 30 }

TypeScript Support

Full type definitions included. IntelliSense works out of the box.

import { ShimClient, RepairResponse, StreamingState } from 'shim-sdk';

const shim = new ShimClient({ apiKey: 'sk_test' });

const result: RepairResponse = await shim.repair({
  raw_output: '{}'
});

// Full IntelliSense support
console.log(result.metadata.confidence); // "high" | "medium" | "low" | "n/a"

Error Handling

The SDK throws errors for network failures and HTTP errors. Shim always returns HTTP 200 with structured error responses.

try {
  const result = await shim.repair({
    raw_output: 'invalid json'
  });

  if (!result.success) {
    console.error('Repair failed:', result.metadata.errors);
  }
} catch (error) {
  console.error('Network error:', error);
}

Support

Docs: docs.shim.so
Issues: GitHub Issues

License

MIT