@nimblebrain/mpak-sdk 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,292 @@
+import { VersionDetail, DownloadInfo, VersionsResponse, PlatformInfo, FullProvenance, SkillSummary, SkillDetail, BundleSearchResponse, BundleDetail, SkillSearchResponse, SkillDownloadInfo } from '@nimblebrain/mpak-schemas';
+export { Bundle, BundleDetail, BundleDetail as BundleDetailResponse, DownloadInfo as BundleDownloadResponse, BundleSearchResponse, VersionDetail as BundleVersionResponse, VersionsResponse as BundleVersionsResponse, Pagination, SkillDetail, SkillDetail as SkillDetailResponse, SkillDownloadInfo, SkillDownloadInfo as SkillDownloadResponse, SkillSearchResponse } from '@nimblebrain/mpak-schemas';
+
+/**
+ * SDK-specific type definitions for mpak SDK
+ *
+ * API response types are re-exported from @nimblebrain/mpak-schemas.
+ * This file contains SDK-specific types (client config, skill references, etc.)
+ */
+
+/** Version in versions listing */
+type BundleVersion = VersionsResponse['versions'][number];
+/** Artifact in version detail */
+type BundleArtifact = VersionDetail['artifacts'][number];
+/** Download info alias */
+type BundleDownloadInfo = DownloadInfo;
+/** Skill summary in search results */
+type Skill = SkillSummary;
+
+/** Skill version in detail */
+type SkillVersion = SkillDetail['versions'][number];
+/** Platform identifier (os + arch) */
+type Platform = PlatformInfo;
+
+/** Provenance information for verified packages */
+type Provenance = FullProvenance;
+/** Author information */
+interface Author {
+    name: string;
+    url?: string;
+    email?: string;
+}
+/** Query parameters for bundle search */
+interface BundleSearchParams {
+    q?: string;
+    type?: string;
+    sort?: 'downloads' | 'recent' | 'name';
+    limit?: number;
+    offset?: number;
+}
+/** Query parameters for skill search */
+interface SkillSearchParams {
+    q?: string;
+    tags?: string;
+    category?: string;
+    surface?: string;
+    sort?: 'downloads' | 'recent' | 'name';
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Configuration options for MpakClient
+ */
+interface MpakClientConfig {
+    /**
+     * Base URL for the mpak registry API
+     * @default 'https://registry.mpak.dev'
+     */
+    registryUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * User-Agent string sent with every request
+     * @example 'mpak-cli/0.2.0'
+     */
+    userAgent?: string;
+}
+/**
+ * Base fields shared by all skill reference types
+ */
+interface SkillReferenceBase {
+    /** Skill artifact identifier (e.g., '@nimbletools/folk-crm') */
+    name: string;
+    /** Semver version (e.g., '1.0.0') or 'latest' */
+    version: string;
+    /** SHA256 integrity hash (format: 'sha256-hexdigest') */
+    integrity?: string;
+}
+/**
+ * Skill reference from mpak registry
+ */
+interface MpakSkillReference extends SkillReferenceBase {
+    source: 'mpak';
+}
+/**
+ * Skill reference from GitHub repository
+ */
+interface GithubSkillReference extends SkillReferenceBase {
+    source: 'github';
+    /** GitHub repository (owner/repo) */
+    repo: string;
+    /** Path to skill file in repo */
+    path: string;
+}
+/**
+ * Skill reference from direct URL
+ */
+interface UrlSkillReference extends SkillReferenceBase {
+    source: 'url';
+    /** Direct download URL */
+    url: string;
+}
+/**
+ * Discriminated union of skill reference types
+ */
+type SkillReference = MpakSkillReference | GithubSkillReference | UrlSkillReference;
+/**
+ * Result of resolving a skill reference
+ */
+interface ResolvedSkill {
+    /** The markdown content of the skill */
+    content: string;
+    /** Version that was resolved */
+    version: string;
+    /** Source the skill was fetched from */
+    source: 'mpak' | 'github' | 'url';
+    /** Whether integrity was verified */
+    verified: boolean;
+}
+
+/**
+ * Client for interacting with the mpak registry
+ *
+ * Requires Node.js 18+ for native fetch support.
+ * Uses jszip for skill bundle extraction.
+ */
+declare class MpakClient {
+    private readonly registryUrl;
+    private readonly timeout;
+    private readonly userAgent;
+    constructor(config?: MpakClientConfig);
+    /**
+     * Search for bundles
+     */
+    searchBundles(params?: BundleSearchParams): Promise<BundleSearchResponse>;
+    /**
+     * Get bundle details
+     */
+    getBundle(name: string): Promise<BundleDetail>;
+    /**
+     * Get all versions of a bundle
+     */
+    getBundleVersions(name: string): Promise<VersionsResponse>;
+    /**
+     * Get a specific version of a bundle
+     */
+    getBundleVersion(name: string, version: string): Promise<VersionDetail>;
+    /**
+     * Get download info for a bundle
+     */
+    getBundleDownload(name: string, version: string, platform?: Platform): Promise<DownloadInfo>;
+    /**
+     * Search for skills
+     */
+    searchSkills(params?: SkillSearchParams): Promise<SkillSearchResponse>;
+    /**
+     * Get skill details
+     */
+    getSkill(name: string): Promise<SkillDetail>;
+    /**
+     * Get download info for a skill (latest version)
+     */
+    getSkillDownload(name: string): Promise<SkillDownloadInfo>;
+    /**
+     * Get download info for a specific skill version
+     */
+    getSkillVersionDownload(name: string, version: string): Promise<SkillDownloadInfo>;
+    /**
+     * Download skill content and verify integrity
+     *
+     * @throws {MpakIntegrityError} If expectedSha256 is provided and doesn't match (fail-closed)
+     */
+    downloadSkillContent(downloadUrl: string, expectedSha256?: string): Promise<{
+        content: string;
+        verified: boolean;
+    }>;
+    /**
+     * Resolve a skill reference to actual content
+     *
+     * Supports mpak, github, and url sources. This is the main method for
+     * fetching skill content from any supported source.
+     *
+     * @throws {MpakNotFoundError} If skill not found
+     * @throws {MpakIntegrityError} If integrity check fails (fail-closed)
+     * @throws {MpakNetworkError} For network failures
+     *
+     * @example
+     * ```typescript
+     * // Resolve from mpak registry
+     * const skill = await client.resolveSkillRef({
+     *   source: 'mpak',
+     *   name: '@nimblebraininc/folk-crm',
+     *   version: '1.3.0',
+     * });
+     *
+     * // Resolve from GitHub
+     * const skill = 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 skill = await client.resolveSkillRef({
+     *   source: 'url',
+     *   name: '@example/custom',
+     *   version: '1.0.0',
+     *   url: 'https://example.com/skill.md',
+     * });
+     * ```
+     */
+    resolveSkillRef(ref: SkillReference): Promise<ResolvedSkill>;
+    /**
+     * Resolve a skill from mpak registry
+     *
+     * The API returns a ZIP bundle containing SKILL.md and metadata.
+     */
+    private resolveMpakSkill;
+    /**
+     * Resolve a skill from GitHub releases
+     */
+    private resolveGithubSkill;
+    /**
+     * Resolve a skill from a direct URL
+     */
+    private resolveUrlSkill;
+    /**
+     * Extract SKILL.md content from a skill bundle ZIP
+     */
+    private extractSkillFromZip;
+    /**
+     * Verify content integrity and throw if mismatch (fail-closed)
+     */
+    private verifyIntegrityOrThrow;
+    /**
+     * Extract hash from integrity string (removes prefix)
+     */
+    private extractHash;
+    /**
+     * Detect the current platform
+     */
+    static detectPlatform(): Platform;
+    /**
+     * Compute SHA256 hash of content
+     */
+    private computeSha256;
+    /**
+     * Validate that a name is scoped (@scope/name)
+     */
+    private validateScopedName;
+    /**
+     * Fetch with timeout support
+     */
+    private fetchWithTimeout;
+}
+
+/**
+ * Base error class for mpak SDK errors
+ */
+declare class MpakError extends Error {
+    code: string;
+    statusCode: number | undefined;
+    constructor(message: string, code: string, statusCode?: number);
+}
+/**
+ * Thrown when a requested resource is not found (404)
+ */
+declare class MpakNotFoundError extends MpakError {
+    constructor(resource: string);
+}
+/**
+ * Thrown when integrity verification fails (hash mismatch)
+ * This is a fail-closed error - content is NOT returned when this is thrown
+ */
+declare class MpakIntegrityError extends MpakError {
+    expected: string;
+    actual: string;
+    constructor(expected: string, actual: string);
+}
+/**
+ * Thrown for network-related failures (timeouts, connection errors)
+ */
+declare class MpakNetworkError extends MpakError {
+    constructor(message: string);
+}
+
+export { type Author, type BundleArtifact, type BundleDownloadInfo, type BundleSearchParams, type BundleVersion, type GithubSkillReference, MpakClient, type MpakClientConfig, MpakError, MpakIntegrityError, MpakNetworkError, MpakNotFoundError, type MpakSkillReference, type Platform, type Provenance, type ResolvedSkill, type Skill, type SkillReference, type SkillSearchParams, type SkillVersion, type UrlSkillReference };

package/dist/index.d.ts

@@ -1,39 +1,292 @@
+import { VersionDetail, DownloadInfo, VersionsResponse, PlatformInfo, FullProvenance, SkillSummary, SkillDetail, BundleSearchResponse, BundleDetail, SkillSearchResponse, SkillDownloadInfo } from '@nimblebrain/mpak-schemas';
+export { Bundle, BundleDetail, BundleDetail as BundleDetailResponse, DownloadInfo as BundleDownloadResponse, BundleSearchResponse, VersionDetail as BundleVersionResponse, VersionsResponse as BundleVersionsResponse, Pagination, SkillDetail, SkillDetail as SkillDetailResponse, SkillDownloadInfo, SkillDownloadInfo as SkillDownloadResponse, SkillSearchResponse } from '@nimblebrain/mpak-schemas';
+
 /**
- * @nimblebrain/mpak-sdk
+ * SDK-specific type definitions for mpak SDK
  *
- * TypeScript SDK for mpak registry - MCPB bundles and Agent Skills
+ * API response types are re-exported from @nimblebrain/mpak-schemas.
+ * This file contains SDK-specific types (client config, skill references, etc.)
+ */
+
+/** Version in versions listing */
+type BundleVersion = VersionsResponse['versions'][number];
+/** Artifact in version detail */
+type BundleArtifact = VersionDetail['artifacts'][number];
+/** Download info alias */
+type BundleDownloadInfo = DownloadInfo;
+/** Skill summary in search results */
+type Skill = SkillSummary;
+
+/** Skill version in detail */
+type SkillVersion = SkillDetail['versions'][number];
+/** Platform identifier (os + arch) */
+type Platform = PlatformInfo;
+
+/** Provenance information for verified packages */
+type Provenance = FullProvenance;
+/** Author information */
+interface Author {
+    name: string;
+    url?: string;
+    email?: string;
+}
+/** Query parameters for bundle search */
+interface BundleSearchParams {
+    q?: string;
+    type?: string;
+    sort?: 'downloads' | 'recent' | 'name';
+    limit?: number;
+    offset?: number;
+}
+/** Query parameters for skill search */
+interface SkillSearchParams {
+    q?: string;
+    tags?: string;
+    category?: string;
+    surface?: string;
+    sort?: 'downloads' | 'recent' | 'name';
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Configuration options for MpakClient
+ */
+interface MpakClientConfig {
+    /**
+     * Base URL for the mpak registry API
+     * @default 'https://registry.mpak.dev'
+     */
+    registryUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * User-Agent string sent with every request
+     * @example 'mpak-cli/0.2.0'
+     */
+    userAgent?: string;
+}
+/**
+ * Base fields shared by all skill reference types
+ */
+interface SkillReferenceBase {
+    /** Skill artifact identifier (e.g., '@nimbletools/folk-crm') */
+    name: string;
+    /** Semver version (e.g., '1.0.0') or 'latest' */
+    version: string;
+    /** SHA256 integrity hash (format: 'sha256-hexdigest') */
+    integrity?: string;
+}
+/**
+ * Skill reference from mpak registry
+ */
+interface MpakSkillReference extends SkillReferenceBase {
+    source: 'mpak';
+}
+/**
+ * Skill reference from GitHub repository
+ */
+interface GithubSkillReference extends SkillReferenceBase {
+    source: 'github';
+    /** GitHub repository (owner/repo) */
+    repo: string;
+    /** Path to skill file in repo */
+    path: string;
+}
+/**
+ * Skill reference from direct URL
+ */
+interface UrlSkillReference extends SkillReferenceBase {
+    source: 'url';
+    /** Direct download URL */
+    url: string;
+}
+/**
+ * Discriminated union of skill reference types
+ */
+type SkillReference = MpakSkillReference | GithubSkillReference | UrlSkillReference;
+/**
+ * Result of resolving a skill reference
+ */
+interface ResolvedSkill {
+    /** The markdown content of the skill */
+    content: string;
+    /** Version that was resolved */
+    version: string;
+    /** Source the skill was fetched from */
+    source: 'mpak' | 'github' | 'url';
+    /** Whether integrity was verified */
+    verified: boolean;
+}
+
+/**
+ * Client for interacting with the mpak registry
  *
  * Requires Node.js 18+ for native fetch support.
- *
- * @example
- * ```typescript
- * import { MpakClient, SkillReference } from '@nimblebrain/mpak-sdk';
- *
- * const client = new MpakClient();
- *
- * // Search for bundles
- * const bundles = await client.searchBundles({ q: 'mcp' });
- *
- * // Get bundle details
- * const bundle = await client.getBundle('@nimbletools/echo');
- *
- * // Search for skills
- * const skills = await client.searchSkills({ q: 'crm' });
- *
- * // Resolve a skill reference to content (recommended)
- * const ref: SkillReference = {
- *   source: 'mpak',
- *   name: '@nimblebraininc/folk-crm',
- *   version: '1.3.0',
- * };
- * const resolved = await client.resolveSkillRef(ref);
- * console.log(resolved.content); // Skill markdown content
- * ```
- */
-export { MpakClient } from './client.js';
-export type { MpakClientConfig } from './types.js';
-export type { BundleSearchResponse, BundleDetailResponse, BundleVersionsResponse, BundleVersionResponse, BundleDownloadResponse, BundleIndexResponse, BundleSearchParams, Bundle, BundleDetail, BundleVersion, BundleArtifact, BundleDownloadInfo, } from './types.js';
-export type { SkillSearchResponse, SkillDetailResponse, SkillDownloadResponse, SkillSearchParams, Skill, SkillDetail, SkillDownloadInfo, SkillVersion, SkillReference, MpakSkillReference, GithubSkillReference, UrlSkillReference, ResolvedSkill, } from './types.js';
-export type { Platform, Pagination, Provenance, Author, } from './types.js';
-export { MpakError, MpakNotFoundError, MpakIntegrityError, MpakNetworkError, } from './errors.js';
-//# sourceMappingURL=index.d.ts.map
+ * Uses jszip for skill bundle extraction.
+ */
+declare class MpakClient {
+    private readonly registryUrl;
+    private readonly timeout;
+    private readonly userAgent;
+    constructor(config?: MpakClientConfig);
+    /**
+     * Search for bundles
+     */
+    searchBundles(params?: BundleSearchParams): Promise<BundleSearchResponse>;
+    /**
+     * Get bundle details
+     */
+    getBundle(name: string): Promise<BundleDetail>;
+    /**
+     * Get all versions of a bundle
+     */
+    getBundleVersions(name: string): Promise<VersionsResponse>;
+    /**
+     * Get a specific version of a bundle
+     */
+    getBundleVersion(name: string, version: string): Promise<VersionDetail>;
+    /**
+     * Get download info for a bundle
+     */
+    getBundleDownload(name: string, version: string, platform?: Platform): Promise<DownloadInfo>;
+    /**
+     * Search for skills
+     */
+    searchSkills(params?: SkillSearchParams): Promise<SkillSearchResponse>;
+    /**
+     * Get skill details
+     */
+    getSkill(name: string): Promise<SkillDetail>;
+    /**
+     * Get download info for a skill (latest version)
+     */
+    getSkillDownload(name: string): Promise<SkillDownloadInfo>;
+    /**
+     * Get download info for a specific skill version
+     */
+    getSkillVersionDownload(name: string, version: string): Promise<SkillDownloadInfo>;
+    /**
+     * Download skill content and verify integrity
+     *
+     * @throws {MpakIntegrityError} If expectedSha256 is provided and doesn't match (fail-closed)
+     */
+    downloadSkillContent(downloadUrl: string, expectedSha256?: string): Promise<{
+        content: string;
+        verified: boolean;
+    }>;
+    /**
+     * Resolve a skill reference to actual content
+     *
+     * Supports mpak, github, and url sources. This is the main method for
+     * fetching skill content from any supported source.
+     *
+     * @throws {MpakNotFoundError} If skill not found
+     * @throws {MpakIntegrityError} If integrity check fails (fail-closed)
+     * @throws {MpakNetworkError} For network failures
+     *
+     * @example
+     * ```typescript
+     * // Resolve from mpak registry
+     * const skill = await client.resolveSkillRef({
+     *   source: 'mpak',
+     *   name: '@nimblebraininc/folk-crm',
+     *   version: '1.3.0',
+     * });
+     *
+     * // Resolve from GitHub
+     * const skill = 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 skill = await client.resolveSkillRef({
+     *   source: 'url',
+     *   name: '@example/custom',
+     *   version: '1.0.0',
+     *   url: 'https://example.com/skill.md',
+     * });
+     * ```
+     */
+    resolveSkillRef(ref: SkillReference): Promise<ResolvedSkill>;
+    /**
+     * Resolve a skill from mpak registry
+     *
+     * The API returns a ZIP bundle containing SKILL.md and metadata.
+     */
+    private resolveMpakSkill;
+    /**
+     * Resolve a skill from GitHub releases
+     */
+    private resolveGithubSkill;
+    /**
+     * Resolve a skill from a direct URL
+     */
+    private resolveUrlSkill;
+    /**
+     * Extract SKILL.md content from a skill bundle ZIP
+     */
+    private extractSkillFromZip;
+    /**
+     * Verify content integrity and throw if mismatch (fail-closed)
+     */
+    private verifyIntegrityOrThrow;
+    /**
+     * Extract hash from integrity string (removes prefix)
+     */
+    private extractHash;
+    /**
+     * Detect the current platform
+     */
+    static detectPlatform(): Platform;
+    /**
+     * Compute SHA256 hash of content
+     */
+    private computeSha256;
+    /**
+     * Validate that a name is scoped (@scope/name)
+     */
+    private validateScopedName;
+    /**
+     * Fetch with timeout support
+     */
+    private fetchWithTimeout;
+}
+
+/**
+ * Base error class for mpak SDK errors
+ */
+declare class MpakError extends Error {
+    code: string;
+    statusCode: number | undefined;
+    constructor(message: string, code: string, statusCode?: number);
+}
+/**
+ * Thrown when a requested resource is not found (404)
+ */
+declare class MpakNotFoundError extends MpakError {
+    constructor(resource: string);
+}
+/**
+ * Thrown when integrity verification fails (hash mismatch)
+ * This is a fail-closed error - content is NOT returned when this is thrown
+ */
+declare class MpakIntegrityError extends MpakError {
+    expected: string;
+    actual: string;
+    constructor(expected: string, actual: string);
+}
+/**
+ * Thrown for network-related failures (timeouts, connection errors)
+ */
+declare class MpakNetworkError extends MpakError {
+    constructor(message: string);
+}
+
+export { type Author, type BundleArtifact, type BundleDownloadInfo, type BundleSearchParams, type BundleVersion, type GithubSkillReference, MpakClient, type MpakClientConfig, MpakError, MpakIntegrityError, MpakNetworkError, MpakNotFoundError, type MpakSkillReference, type Platform, type Provenance, type ResolvedSkill, type Skill, type SkillReference, type SkillSearchParams, type SkillVersion, type UrlSkillReference };