TypeScript SDK Reference

Complete API reference for the @musher-dev/musher-sdk package. The SDK requires Node.js 20+ and has a single runtime dependency (zod).

Module-Level Functions

`pull(ref: string, version?: string): Promise<Bundle>`

Resolve, fetch, verify, and cache a bundle. Returns a Bundle with typed access to its contents. Uses the global configuration set via configure().

typescript

import { pull } from "@musher-dev/musher-sdk";

const bundle = await pull("acme/code-review-kit");
const pinned = await pull("acme/code-review-kit", "1.2.3");

`resolve(ref: string, version?: string): Promise<BundleResolveOutput>`

Resolve a bundle reference to its manifest metadata without downloading asset content. Useful for inspecting versions, listing assets, or validating a reference.

`configure(config: Partial<ClientConfig>): void`

Set global SDK configuration. Affects all subsequent calls to pull() and resolve().

typescript

import { configure } from "@musher-dev/musher-sdk";

configure({
  apiKey: "mush_...",
  baseUrl: "https://api.musher.dev",
  cacheDir: "/custom/cache",
  manifestTtlSeconds: 3600,
});

`getClient(): MusherClient`

Get or create the global MusherClient instance.

MusherClient

Client class for custom configuration. Use this when you need multiple clients with different settings or want explicit control over the client lifecycle.

typescript

import { MusherClient } from "@musher-dev/musher-sdk";

const client = new MusherClient({
  apiKey: "mush_...",
  baseUrl: "https://api.musher.dev",
});

const bundle = await client.pull("acme/code-review-kit");

Constructor: `ClientConfig`

Field	Type	Default	Description
`apiKey`	`string`	Auto-discovered	API token (overrides credential discovery)
`baseUrl`	`string`	`"https://api.musher.dev"`	Registry base URL
`cacheDir`	`string`	Platform default	Local cache directory
`manifestTtlSeconds`	`number`	`86400`	Manifest cache TTL in seconds (24 hours)
`timeout`	`number`	`60000`	HTTP request timeout in milliseconds
`retries`	`number`	`3`	Retry count for transient failures

Methods

Method	Returns	Description
`pull(ref, version?)`	`Promise<Bundle>`	Resolve, fetch, verify, and cache a bundle
`resolve(ref, version?)`	`Promise<BundleResolveOutput>`	Resolve metadata without fetching content

`cache` property (`CacheManager`)

Access cache management operations via client.cache.

Method	Returns	Description
`list()`	`Promise<CacheEntry[]>`	List all cached bundle entries
`has(namespace, slug, version?)`	`Promise<boolean>`	Check if a bundle is cached
`remove(namespace, slug, version?)`	`Promise<void>`	Remove a specific cached bundle
`stats()`	`Promise<CacheStats>`	Get aggregate cache statistics
`invalidate(namespace, slug, version?)`	`Promise<void>`	Mark entries as stale (forces re-fetch on next pull)
`clean()`	`Promise<void>`	Remove expired entries and garbage-collect unreferenced blobs
`purge()`	`Promise<void>`	Delete all cached data

Bundle

A resolved bundle with its fetched assets. Returned by pull() and client.pull().

Properties

Property	Type	Description
`manifest`	`BundleManifest`	Bundle metadata including name, version, and asset list

Typed Accessors

Method	Returns	Description
`files()`	`FileHandle[]`	All files in the bundle
`file(logicalPath)`	`FileHandle \| undefined`	Single file by logical path
`skills()`	`SkillHandle[]`	All skills
`skill(name)`	`SkillHandle`	Single skill by name (throws `BundleAssetNotFoundError`)
`prompts()`	`PromptHandle[]`	All prompts
`prompt(name)`	`PromptHandle`	Single prompt by name (throws `BundleAssetNotFoundError`)
`toolsets()`	`ToolsetHandle[]`	All toolsets
`toolset(name)`	`ToolsetHandle`	Single toolset by name (throws `BundleAssetNotFoundError`)
`agentSpecs()`	`AgentSpecHandle[]`	All agent specs
`agentSpec(name)`	`AgentSpecHandle`	Single agent spec by name (throws `BundleAssetNotFoundError`)

Selection

select(filter) returns a Selection — a filtered view of the bundle with the same typed accessor methods.

typescript

const bundle = await pull("acme/code-review-kit");

const subset = bundle.select({
  skills: ["code-review"],
  prompts: ["system"],
});

for (const skill of subset.skills()) {
  console.log(skill.name);
}

Integrity and Lockfile

Method	Returns	Description
`verify()`	`Promise<void>`	Re-verify SHA-256 checksums for all assets
`writeLockfile(path?)`	`Promise<void>`	Export metadata and hashes as a lockfile

Handle Types

`FileHandle`

Member	Type	Description
`.path`	`string`	Original path from the manifest
`.logicalPath`	`string`	Logical path within the bundle
`.mediaType`	`string \| undefined`	MIME type, if known
`.size`	`number`	File size in bytes
`.digest`	`string`	SHA-256 content digest
`.text()`	`string`	Decode content as UTF-8 text
`.bytes()`	`Uint8Array`	Raw content bytes
`.stream()`	`ReadableStream`	Stream content

`SkillHandle`

Member	Type	Description
`.name`	`string`	Skill name
`.content`	`string`	SKILL.md text content
`.description`	`string`	Skill description (from frontmatter)
`.files()`	`FileHandle[]`	All files within this skill
`.file(relativePath)`	`FileHandle \| undefined`	Single file within the skill by relative path

`PromptHandle`

Member	Type	Description
`.name`	`string`	Prompt name
`.content`	`string`	Prompt text content

`ToolsetHandle`

Member	Type	Description
`.name`	`string`	Toolset name
`.content`	`string`	Toolset content (typically JSON)

`AgentSpecHandle`

Member	Type	Description
`.name`	`string`	Agent spec name
`.content`	`string`	Agent spec content (typically JSON)

Adapter Functions

Export bundle content into formats for Claude, OpenAI, and VS Code. These functions are imported directly from the SDK.

Function	Description
`exportClaudePlugin(bundle)`	Export skills as a Claude Desktop plugin directory
`installClaudeSkills(bundle)`	Install skills to `.claude/skills/`
`exportOpenAILocalSkill(bundle)`	Export a skill as an OpenAI-compatible local file
`exportOpenAIInlineSkill(bundle)`	Export a skill as base64-encoded inline content
`installVSCodeSkills(bundle)`	Install skills to `.agents/skills/` for VS Code

typescript

import { pull, exportClaudePlugin, installVSCodeSkills } from "@musher-dev/musher-sdk";

const bundle = await pull("acme/code-review-kit");

// Export as Claude plugin
await exportClaudePlugin(bundle);

// Install skills for VS Code
await installVSCodeSkills(bundle);

Selection

A Selection is a filtered view of a Bundle. It has the same typed accessor methods (skills(), prompts(), etc.) but only returns assets matching the filter.

typescript

const selection = bundle.select({
  skills: ["code-review", "security-scan"],
  prompts: ["review-template"],
});

// Only the selected assets are returned
for (const skill of selection.skills()) {
  console.log(skill.name);
}

Cache Types

`CacheEntry`

Field	Type	Description
`namespace`	`string`	Bundle namespace
`slug`	`string`	Bundle slug
`version`	`string`	Semver version string
`fresh`	`boolean`	Whether the entry is within its TTL

`CacheStats`

Field	Type	Description
`entryCount`	`number`	Total number of cached entries
`freshCount`	`number`	Number of entries within their TTL
`staleCount`	`number`	Number of expired entries
`blobCount`	`number`	Number of content-addressable blobs on disk
`blobSizeBytes`	`number`	Total blob size in bytes

Errors

All errors inherit from MusherError.

Error	When
`MusherError`	Base class for all SDK errors
`ApiError`	API returned an error (carries `ProblemDetail`)
`AuthenticationError`	Invalid or missing credentials
`NotFoundError`	Bundle or version does not exist
`ForbiddenError`	Valid credentials but insufficient permissions
`ValidationError`	Request failed server-side validation
`RateLimitError`	Too many requests
`NetworkError`	Connection or DNS resolution failure
`TimeoutError`	Request exceeded configured timeout
`CacheError`	Failed to read or write local cache
`IntegrityError`	SHA-256 checksum mismatch
`SchemaError`	API response failed Zod schema validation
`BundleAssetNotFoundError`	Requested asset does not exist in bundle

Enums

`AssetType`

"agent_definition", "skill", "tool_config", "prompt", "config", "other"

`BundleVisibility`

"private", "public"

`BundleVersionState`

"published", "yanked"

BundleRef

Parsed bundle reference. Supports three formats:

namespace/slug — resolves to latest version
namespace/slug:version — specific version or semver range
namespace/slug@sha256:digest — pinned by content digest

Field	Type	Description
`namespace`	`string`	Organization or user namespace
`slug`	`string`	Bundle slug
`version`	`string \| undefined`	Semver version or range
`digest`	`string \| undefined`	Content digest for pinning

TypeScript SDK Reference

Module-Level Functions

pull(ref: string, version?: string): Promise<Bundle>

resolve(ref: string, version?: string): Promise<BundleResolveOutput>

configure(config: Partial<ClientConfig>): void

getClient(): MusherClient

MusherClient

Constructor: ClientConfig

Methods

cache property (CacheManager)

Bundle

Properties

Typed Accessors

Selection

Integrity and Lockfile

Handle Types

FileHandle

SkillHandle

PromptHandle

ToolsetHandle

AgentSpecHandle

Adapter Functions

Selection

Cache Types

CacheEntry

CacheStats

Errors

Enums

AssetType

BundleVisibility

BundleVersionState

BundleRef

`pull(ref: string, version?: string): Promise<Bundle>`

`resolve(ref: string, version?: string): Promise<BundleResolveOutput>`

`configure(config: Partial<ClientConfig>): void`

`getClient(): MusherClient`

Constructor: `ClientConfig`

`cache` property (`CacheManager`)

`FileHandle`

`SkillHandle`

`PromptHandle`

`ToolsetHandle`

`AgentSpecHandle`

`CacheEntry`

`CacheStats`

`AssetType`

`BundleVisibility`

`BundleVersionState`