@nimblebrain/mpak-sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,23 +1,20 @@
 # @nimblebrain/mpak-sdk
 
-TypeScript SDK for mpak registry - MCPB bundles and Agent Skills.
+[![CI](https://github.com/NimbleBrainInc/mpak/actions/workflows/sdk-typescript-ci.yml/badge.svg)](https://github.com/NimbleBrainInc/mpak/actions/workflows/sdk-typescript-ci.yml)
+[![npm](https://img.shields.io/npm/v/@nimblebrain/mpak-sdk)](https://www.npmjs.com/package/@nimblebrain/mpak-sdk)
+[![Node](https://img.shields.io/node/v/@nimblebrain/mpak-sdk)](https://www.npmjs.com/package/@nimblebrain/mpak-sdk)
+[![License](https://img.shields.io/npm/l/@nimblebrain/mpak-sdk)](https://github.com/NimbleBrainInc/mpak/blob/main/packages/sdk-typescript/LICENSE)
+[![mpak.dev](https://mpak.dev/badge.svg)](https://mpak.dev)
 
-## Features
-
-- Zero runtime dependencies (native `fetch` and `crypto` only)
-- Requires Node.js 18+
-- Type-safe API (types generated from OpenAPI spec)
-- Fail-closed integrity verification
+TypeScript SDK for the mpak registry - search, download, and resolve MCPB bundles and Agent Skills.
 
 ## Installation
 
 ```bash
-npm install @nimblebrain/mpak-sdk
+pnpm add @nimblebrain/mpak-sdk
 ```
 
-## Usage
-
-### Search Bundles
+## Quick Start
 
 ```typescript
 import { MpakClient } from '@nimblebrain/mpak-sdk';
@@ -26,12 +23,18 @@ const client = new MpakClient();
 
 // Search for bundles
 const results = await client.searchBundles({ q: 'mcp', limit: 10 });
-
 for (const bundle of results.bundles) {
   console.log(`${bundle.name}@${bundle.latest_version}`);
 }
+
+// Get download info
+const download = await client.getBundleDownload('@nimblebraininc/echo', 'latest');
+console.log(`Download URL: ${download.url}`);
+console.log(`SHA256: ${download.bundle.sha256}`);
 ```
 
+## Usage
+
 ### Get Bundle Details
 
 ```typescript
@@ -41,20 +44,6 @@ console.log(bundle.description);
 console.log(`Versions: ${bundle.versions.map(v => v.version).join(', ')}`);
 ```
 
-### Download a Bundle
-
-```typescript
-// Get download info for the latest version
-const versions = await client.getBundleVersions('@nimblebraininc/echo');
-const download = await client.getBundleDownload(
-  '@nimblebraininc/echo',
-  versions.latest
-);
-
-console.log(`Download URL: ${download.url}`);
-console.log(`SHA256: ${download.bundle.sha256}`);
-```
-
 ### Platform-Specific Downloads
 
 ```typescript
@@ -99,6 +88,39 @@ console.log(`Verified: ${verified}`);
 console.log(content);
 ```
 
+### Resolve Skill References
+
+```typescript
+import { MpakClient, SkillReference } from '@nimblebrain/mpak-sdk';
+
+const client = new MpakClient();
+
+// Resolve from mpak registry
+const skill = await client.resolveSkillRef({
+  source: 'mpak',
+  name: '@nimblebraininc/folk-crm',
+  version: '1.3.0',
+});
+console.log(skill.content);
+
+// Resolve from GitHub
+const ghSkill = await client.resolveSkillRef({
+  source: 'github',
+  name: '@example/my-skill',
+  version: 'v1.0.0',
+  repo: 'owner/repo',
+  path: 'skills/my-skill/SKILL.md',
+});
+
+// Resolve from URL
+const urlSkill = await client.resolveSkillRef({
+  source: 'url',
+  name: '@example/custom',
+  version: '1.0.0',
+  url: 'https://example.com/skill.md',
+});
+```
+
 ## Error Handling
 
 ```typescript
@@ -131,7 +153,7 @@ try {
 
 ```typescript
 const client = new MpakClient({
-  registryUrl: 'https://api.mpak.dev', // Custom registry URL
+  registryUrl: 'https://registry.mpak.dev', // Custom registry URL
   timeout: 30000, // Request timeout in ms
 });
 ```
@@ -155,6 +177,7 @@ const client = new MpakClient({
 - `getSkillDownload(name)` - Get latest version download
 - `getSkillVersionDownload(name, version)` - Get specific version download
 - `downloadSkillContent(url, expectedSha256?)` - Download with optional integrity check
+- `resolveSkillRef(ref)` - Resolve a skill reference to content
 
 #### Static Methods
 
@@ -171,39 +194,64 @@ const client = new MpakClient({
 
 ```bash
 # Install dependencies
-npm install
+pnpm install
 
 # Run unit tests
-npm run test
+pnpm test
 
 # Run integration tests (hits real API)
-npm run test:integration
+pnpm test:integration
 
 # Type check
-npm run typecheck
-
-# Lint
-npm run lint
-
-# Full verification
-npm run verify
-
-# Generate types from OpenAPI spec
-npm run generate:types
+pnpm typecheck
 
 # Build
-npm run build
+pnpm build
 ```
 
-## Type Generation
+### Verification
 
-Types are generated from the mpak.dev OpenAPI spec using `openapi-typescript`:
+Run all checks before submitting changes:
 
 ```bash
-npm run generate:types
+pnpm --filter @nimblebrain/mpak-sdk lint           # lint
+pnpm --filter @nimblebrain/mpak-sdk exec prettier --check "src/**/*.ts" "tests/**/*.ts"  # format
+pnpm --filter @nimblebrain/mpak-sdk typecheck       # type check
+pnpm --filter @nimblebrain/mpak-sdk test            # unit tests
+pnpm --filter @nimblebrain/mpak-sdk test:integration  # integration tests (hits live registry)
 ```
 
-This fetches the spec from `https://api.mpak.dev/documentation/json` and generates `src/schema.d.ts`.
+CI runs lint, format check, typecheck, and unit tests on every PR via [`sdk-typescript-ci.yml`](../../.github/workflows/sdk-typescript-ci.yml).
+
+## Releasing
+
+Releases are automated via GitHub Actions. The publish workflow is triggered by git tags.
+
+**Version is defined in one place:** `package.json`.
+
+### Steps
+
+1. **Bump version** in `package.json`:
+   ```bash
+   cd packages/sdk-typescript
+   npm version patch   # 0.1.0 -> 0.1.1
+   npm version minor   # 0.1.0 -> 0.2.0
+   npm version major   # 0.1.0 -> 1.0.0
+   ```
+
+2. **Commit and push:**
+   ```bash
+   git commit -am "sdk-typescript: bump to X.Y.Z"
+   git push
+   ```
+
+3. **Tag and push** (this triggers the publish):
+   ```bash
+   git tag sdk-typescript-vX.Y.Z
+   git push origin sdk-typescript-vX.Y.Z
+   ```
+
+CI will run the full verification suite, verify the tag matches `package.json`, build, and publish to npm. See [`sdk-typescript-publish.yml`](../../.github/workflows/sdk-typescript-publish.yml).
 
 ## License