@linkyourskill/mcp-client 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @linkyourskill/mcp-client
+
+Official TypeScript / Node.js SDK for the [LinkYourSkill](https://linkyourskill.ai) agent API.
+Search Skillanbieter (service providers), prepare orders for agentowner approval,
+and track order status — from any AI agent or backend.
+
+> This is a thin, typed wrapper over the public REST agent API (`/api/agent/*`).
+> It has **zero runtime dependencies** (uses the global `fetch`, Node 18+).
+
+## Install
+
+```bash
+npm install @linkyourskill/mcp-client
+```
+
+## Quick start
+
+```ts
+import { createClient } from '@linkyourskill/mcp-client';
+
+const lys = createClient({
+  token: process.env.LYS_TOKEN!,
+  // url: 'http://localhost'  // optional — defaults to https://linkyourskill.ai
+});
+
+// Search for providers
+const providers = await lys.searchSkillanbieter({
+  query: 'Klempner',
+  service_area: 'Berlin',
+});
+
+// Create an order (sent to the agentowner for WhatsApp approval)
+const order = await lys.prepareOrder({
+  title: 'Wasserhahn reparieren',
+  description: 'Tropfender Wasserhahn in der Küche',
+  location: 'Berlin Mitte',
+  timeframe: 'Nächste Woche',
+  price_range_min: 50,
+  price_range_max: 120,
+});
+
+// Track status
+const status = await lys.getOrderStatus({ order_id: order.id });
+console.log(status.status); // e.g. "pending_approval"
+```
+
+## Authentication
+
+Every call is authenticated with a bearer token (`lys_…`). Mint one in the
+agentowner dashboard, or use the read-only demo token from the
+[API docs](https://linkyourskill.ai/docs/api). The SDK sends it as
+`Authorization: Bearer <token>`.
+
+## Configuration
+
+`createClient(options)`:
+
+| Option  | Type             | Default                     | Description |
+|---------|------------------|-----------------------------|-------------|
+| `token` | `string`         | — (required)                | Agent API token. |
+| `url`   | `string`         | `https://linkyourskill.ai`  | API origin. The SDK appends `/api/agent/*`. Point at `http://localhost` for a local stack. |
+| `fetch` | `typeof fetch`   | global `fetch`              | Custom fetch (testing / non-standard runtimes). |
+
+## API reference
+
+| Method | Maps to | Description |
+|--------|---------|-------------|
+| `searchSkillanbieter(params?)` | `GET /api/agent/skillanbieter/search` | Search providers by query, category, area, rating, availability, geo. |
+| `getSkillanbieterRatings({ skillanbieter_id, page?, limit? })` | `GET …/skillanbieter/:id/ratings` | Ratings & reviews for one provider. |
+| `prepareOrder(params)` | `POST /api/agent/orders` | Create an order for agentowner approval. |
+| `listOrders({ status?, page?, limit? })` | `GET /api/agent/orders` | List this agent's orders. |
+| `listActiveOrders()` | `GET /api/agent/orders?status=…` | Only non-terminal orders. |
+| `getOrder({ order_id })` | `GET /api/agent/orders/:id` | Full order incl. event timeline. |
+| `getOrderStatus({ order_id })` | derived from `GET …/orders/:id` | Condensed status + last event + transition path. |
+| `getOrderEvents({ order_id })` | derived from `GET …/orders/:id` | Raw event timeline. |
+| `getProfile()` | `GET /api/agent/profile` | This token's agent profile and scopes. |
+
+### Error handling
+
+Any non-2xx response throws a `LysApiError`:
+
+```ts
+import { LysApiError } from '@linkyourskill/mcp-client';
+
+try {
+  await lys.prepareOrder({ /* … */ });
+} catch (err) {
+  if (err instanceof LysApiError) {
+    console.error(err.status, err.code, err.message); // e.g. 400 "validation_error" "title is required"
+  }
+}
+```
+
+## MCP transport
+
+Prefer raw [Model Context Protocol](https://linkyourskill.ai/docs/mcp-integration)?
+The same capabilities are exposed as 18 MCP tools at `POST /mcp`. This SDK targets
+the REST surface so methods return plain typed objects; use the MCP endpoint
+directly when you want tool-calling from an MCP-native agent.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest unit tests (mocked fetch)
+npm run typecheck
+```
+
+End-to-end coverage against a live stack lives in the root Playwright suite
+(`tests/e2e/sdk-client.spec.ts`).
+
+## License
+
+UNLICENSED — © LinkYourSkill. Internal/partner use per agreement.

package/dist/client.d.ts

@@ -0,0 +1,63 @@
+import type { AgentProfile, ClientOptions, ListOrdersParams, ListOrdersResult, Order, OrderRef, OrderStatus, PrepareOrderParams, RatingsParams, RatingsResult, SearchParams, SearchResult } from "./types.js";
+/** Default production API origin. */
+export declare const DEFAULT_API_URL = "https://linkyourskill.ai";
+/**
+ * Error thrown for any non-2xx response from the agent API. Carries the HTTP
+ * status plus the structured `{ error, message }` body the API returns.
+ */
+export declare class LysApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/**
+ * Typed client for the LinkYourSkill agent API. Construct via {@link createClient}.
+ *
+ * Every method maps to a documented REST endpoint under `/api/agent/*` and
+ * returns the parsed JSON payload — no MCP transport or response-string parsing.
+ */
+export declare class LysClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    /** Search Skillanbieter (providers). Maps to `GET /api/agent/skillanbieter/search`. */
+    searchSkillanbieter(params?: SearchParams): Promise<SearchResult>;
+    /** Ratings for one provider. Maps to `GET /api/agent/skillanbieter/:id/ratings`. */
+    getSkillanbieterRatings(params: RatingsParams): Promise<RatingsResult>;
+    /**
+     * Prepare an order for agentowner approval (sent via WhatsApp). Maps to
+     * `POST /api/agent/orders`.
+     */
+    prepareOrder(params: PrepareOrderParams): Promise<Order>;
+    /** List this agent's orders. Maps to `GET /api/agent/orders`. */
+    listOrders(params?: ListOrdersParams): Promise<ListOrdersResult>;
+    /** List non-terminal orders. Maps to `GET /api/agent/orders?status=<active>`. */
+    listActiveOrders(): Promise<ListOrdersResult>;
+    /** Full order details incl. event timeline. Maps to `GET /api/agent/orders/:id`. */
+    getOrder(params: OrderRef): Promise<Order>;
+    /**
+     * Condensed status view (current status + last event + transition path).
+     * Derived from `GET /api/agent/orders/:id`, mirroring the MCP `get_order_status` tool.
+     */
+    getOrderStatus(params: OrderRef): Promise<OrderStatus>;
+    /** Full event timeline for an order. Mirrors the MCP `get_order_events` tool. */
+    getOrderEvents(params: OrderRef): Promise<import("./types.js").OrderEvent[]>;
+    /** This token's agent profile and granted scopes. Maps to `GET /api/agent/profile`. */
+    getProfile(): Promise<AgentProfile>;
+    private get;
+    private request;
+}
+/**
+ * Create a LinkYourSkill agent client.
+ *
+ * ```ts
+ * import { createClient } from '@linkyourskill/mcp-client';
+ *
+ * const lys = createClient({ token: process.env.LYS_TOKEN! });
+ * const providers = await lys.searchSkillanbieter({ query: 'Klempner', service_area: 'Berlin' });
+ * ```
+ */
+export declare function createClient(options: ClientOptions): LysClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,EACL,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qCAAqC;AACrC,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAM1D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEf,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAO7E;AAID;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,aAAa;IAiBlC,uFAAuF;IACjF,mBAAmB,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;IAS3E,oFAAoF;IAC9E,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAU5E;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAI9D,iEAAiE;IAC3D,UAAU,CAAC,MAAM,GAAE,gBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQ1E,iFAAiF;IAC3E,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAMnD,oFAAoF;IAC9E,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC;IAKhD;;;OAGG;IACG,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC;IAY5D,iFAAiF;IAC3E,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,YAAY,EAAE,UAAU,EAAE,CAAC;IAOlF,uFAAuF;IACjF,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC;IAMzC,OAAO,CAAC,GAAG;YAIG,OAAO;CAyCtB;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAE9D"}

package/dist/client.js

@@ -0,0 +1,178 @@
+/** Default production API origin. */
+export const DEFAULT_API_URL = "https://linkyourskill.ai";
+/** Active (non-terminal) order statuses — mirrors the MCP `list_active_orders` tool. */
+const ACTIVE_ORDER_STATUSES = "prepared,pending_approval,approved,proposal_submitted,assigned,in_progress";
+/**
+ * Error thrown for any non-2xx response from the agent API. Carries the HTTP
+ * status plus the structured `{ error, message }` body the API returns.
+ */
+export class LysApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.name = "LysApiError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Typed client for the LinkYourSkill agent API. Construct via {@link createClient}.
+ *
+ * Every method maps to a documented REST endpoint under `/api/agent/*` and
+ * returns the parsed JSON payload — no MCP transport or response-string parsing.
+ */
+export class LysClient {
+    token;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        if (!options?.token) {
+            throw new Error("createClient: `token` is required");
+        }
+        this.token = options.token;
+        this.baseUrl = (options.url ?? DEFAULT_API_URL).replace(/\/+$/, "");
+        const f = options.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new Error("createClient: no `fetch` available — pass `fetch` in options or run on Node 18+");
+        }
+        this.fetchImpl = f;
+    }
+    // ── Provider discovery ────────────────────────────────────────────────
+    /** Search Skillanbieter (providers). Maps to `GET /api/agent/skillanbieter/search`. */
+    async searchSkillanbieter(params = {}) {
+        const { query, ...rest } = params;
+        // The REST query param is `q`; the SDK exposes the friendlier `query`.
+        return this.get("/api/agent/skillanbieter/search", {
+            q: query,
+            ...rest,
+        });
+    }
+    /** Ratings for one provider. Maps to `GET /api/agent/skillanbieter/:id/ratings`. */
+    async getSkillanbieterRatings(params) {
+        requireId(params?.skillanbieter_id, "skillanbieter_id");
+        return this.get(`/api/agent/skillanbieter/${encodeURIComponent(params.skillanbieter_id)}/ratings`, { page: params.page, limit: params.limit });
+    }
+    // ── Order lifecycle ───────────────────────────────────────────────────
+    /**
+     * Prepare an order for agentowner approval (sent via WhatsApp). Maps to
+     * `POST /api/agent/orders`.
+     */
+    async prepareOrder(params) {
+        return this.request("POST", "/api/agent/orders", undefined, params);
+    }
+    /** List this agent's orders. Maps to `GET /api/agent/orders`. */
+    async listOrders(params = {}) {
+        return this.get("/api/agent/orders", {
+            status: params.status,
+            page: params.page,
+            limit: params.limit,
+        });
+    }
+    /** List non-terminal orders. Maps to `GET /api/agent/orders?status=<active>`. */
+    async listActiveOrders() {
+        return this.get("/api/agent/orders", {
+            status: ACTIVE_ORDER_STATUSES,
+        });
+    }
+    /** Full order details incl. event timeline. Maps to `GET /api/agent/orders/:id`. */
+    async getOrder(params) {
+        requireId(params?.order_id, "order_id");
+        return this.get(`/api/agent/orders/${encodeURIComponent(params.order_id)}`);
+    }
+    /**
+     * Condensed status view (current status + last event + transition path).
+     * Derived from `GET /api/agent/orders/:id`, mirroring the MCP `get_order_status` tool.
+     */
+    async getOrderStatus(params) {
+        const order = await this.getOrder(params);
+        const events = order.events ?? [];
+        return {
+            id: order.id,
+            status: order.status,
+            events,
+            lastEvent: events.length ? events[events.length - 1] : null,
+            transitions: events.map((e) => e.eventType),
+        };
+    }
+    /** Full event timeline for an order. Mirrors the MCP `get_order_events` tool. */
+    async getOrderEvents(params) {
+        const order = await this.getOrder(params);
+        return order.events ?? [];
+    }
+    // ── Identity ──────────────────────────────────────────────────────────
+    /** This token's agent profile and granted scopes. Maps to `GET /api/agent/profile`. */
+    async getProfile() {
+        return this.get("/api/agent/profile");
+    }
+    // ── internals ─────────────────────────────────────────────────────────
+    get(path, query) {
+        return this.request("GET", path, query);
+    }
+    async request(method, path, query, body) {
+        const url = this.baseUrl + path + buildQuery(query);
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await this.fetchImpl(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!res.ok) {
+            const errObj = (data ?? {});
+            const code = typeof errObj.error === "string" ? errObj.error : `http_${res.status}`;
+            const message = typeof errObj.message === "string"
+                ? errObj.message
+                : `Request to ${path} failed with status ${res.status}`;
+            throw new LysApiError(res.status, code, message, errObj.details);
+        }
+        return data;
+    }
+}
+function requireId(value, name) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required parameter: ${name}`);
+    }
+}
+function buildQuery(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === "")
+            continue;
+        params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+/**
+ * Create a LinkYourSkill agent client.
+ *
+ * ```ts
+ * import { createClient } from '@linkyourskill/mcp-client';
+ *
+ * const lys = createClient({ token: process.env.LYS_TOKEN! });
+ * const providers = await lys.searchSkillanbieter({ query: 'Klempner', service_area: 'Berlin' });
+ * ```
+ */
+export function createClient(options) {
+    return new LysClient(options);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@linkyourskill/mcp-client` — official TypeScript SDK for the LinkYourSkill
+ * agent API. See https://linkyourskill.ai/docs/sdk.
+ */
+export { createClient, LysClient, LysApiError, DEFAULT_API_URL } from "./client.js";
+export type { ClientOptions, SearchParams, Skillanbieter, SearchResult, RatingsParams, Rating, RatingsResult, PrepareOrderParams, Order, OrderEvent, ListOrdersParams, ListOrdersResult, OrderRef, OrderStatus, AgentProfile, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpF,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,MAAM,EACN,aAAa,EACb,kBAAkB,EAClB,KAAK,EACL,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@linkyourskill/mcp-client` — official TypeScript SDK for the LinkYourSkill
+ * agent API. See https://linkyourskill.ai/docs/sdk.
+ */
+export { createClient, LysClient, LysApiError, DEFAULT_API_URL } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Type definitions for the LinkYourSkill agent SDK.
+ *
+ * Response shapes mirror the REST agent API (`/api/agent/*`, see
+ * api/src/routes/agent.ts) and the MCP tool contract (mcp-server/src/tools).
+ * Fields are intentionally permissive ([key: string]: unknown) so the SDK
+ * keeps working when the API adds non-breaking fields.
+ */
+/** Options for {@link createClient}. */
+export interface ClientOptions {
+    /**
+     * Agent API token (`lys_…`). Mint one in the agentowner dashboard or use the
+     * read-only demo token from the docs.
+     */
+    token: string;
+    /**
+     * Base origin of the LinkYourSkill API. The SDK appends `/api/agent/*` paths.
+     * Defaults to the production deployment. For local development point this at
+     * your stack, e.g. `http://localhost` (the reverse proxy routes `/api`).
+     */
+    url?: string;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch` (Node 18+,
+     * Deno, Bun, browsers). Inject one for testing or non-standard runtimes.
+     */
+    fetch?: typeof fetch;
+}
+/** Parameters for {@link LysClient.searchSkillanbieter}. */
+export interface SearchParams {
+    /** Free-text query. Recognises German/English location patterns for distance ranking. */
+    query?: string;
+    /** Exact skill category filter (e.g. "Handwerk", "IT", "Garten"). */
+    category?: string;
+    /** Service-area substring filter. */
+    service_area?: string;
+    /** Preferred city for distance ranking. */
+    location?: string;
+    /** Latitude for precise geo-search (use with `lng`). */
+    lat?: number;
+    /** Longitude for precise geo-search (use with `lat`). */
+    lng?: number;
+    /** Hard distance cap in kilometres (1–500). */
+    radius_km?: number;
+    /** Minimum average rating (1–5). */
+    min_rating?: number;
+    /** Availability day filter. */
+    day?: "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+    /** Availability time `HH:mm` (requires `day`). */
+    time?: string;
+    /** Page number (default 1). */
+    page?: number;
+    /** Results per page (default 50, max 100). */
+    limit?: number;
+}
+export interface Skillanbieter {
+    id: string;
+    displayName: string;
+    skills?: string;
+    averageRating?: number | null;
+    serviceArea?: string | null;
+    distanceKm?: number | null;
+    completedOrders?: number;
+    badges?: Array<{
+        key: string;
+        icon: string;
+    }>;
+    availabilityText?: string | null;
+    skillDescriptions?: string | null;
+    guidelinePriceMin?: number | null;
+    guidelinePriceMax?: number | null;
+    [key: string]: unknown;
+}
+export interface SearchResult {
+    results: Skillanbieter[];
+    page?: number;
+    total?: number;
+    geo?: {
+        location: string | null;
+        lat: number;
+        lng: number;
+        radiusKm: number | null;
+        sortedByDistance: boolean;
+    } | null;
+    [key: string]: unknown;
+}
+export interface RatingsParams {
+    skillanbieter_id: string;
+    page?: number;
+    limit?: number;
+}
+export interface Rating {
+    stars: number;
+    comment?: string | null;
+    createdAt: string;
+    [key: string]: unknown;
+}
+export interface RatingsResult {
+    average: number | null;
+    count: number;
+    ratings: Rating[];
+    [key: string]: unknown;
+}
+/** Parameters for {@link LysClient.prepareOrder}. Mirrors the REST/MCP prepare_order contract. */
+export interface PrepareOrderParams {
+    title: string;
+    description: string;
+    location: string;
+    timeframe: string;
+    price_range_min: number;
+    price_range_max: number;
+    scope?: string;
+    suggested_skillanbieter_id?: string;
+    /** Inquiry broadcast TTL in hours (1–168, default 48). */
+    inquiry_ttl_hours?: number;
+    /** Task category slug; enables structured_data validation. */
+    category_slug?: string;
+    /** Category-specific structured fields. */
+    structured_data?: Record<string, unknown>;
+}
+export interface OrderEvent {
+    eventType: string;
+    actorType: string;
+    createdAt: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+export interface Order {
+    id: string;
+    title: string;
+    status: string;
+    description?: string;
+    scope?: string | null;
+    location?: string;
+    timeframe?: string;
+    priceRangeMin?: number;
+    priceRangeMax?: number;
+    skillanbieterId?: string | null;
+    agentId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    events?: OrderEvent[];
+    [key: string]: unknown;
+}
+export interface ListOrdersParams {
+    /** Status filter — single value or comma-separated list. */
+    status?: string;
+    page?: number;
+    limit?: number;
+}
+export interface ListOrdersResult {
+    orders: Order[];
+    page?: number;
+    total?: number;
+    [key: string]: unknown;
+}
+export interface OrderRef {
+    order_id: string;
+}
+/** Condensed status view returned by {@link LysClient.getOrderStatus}. */
+export interface OrderStatus {
+    id: string;
+    status: string;
+    events: OrderEvent[];
+    /** The most recent event, if any. */
+    lastEvent: OrderEvent | null;
+    /** Ordered list of event types (the state machine path). */
+    transitions: string[];
+}
+export interface AgentProfile {
+    id?: string;
+    name?: string;
+    scopes?: string[];
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for the LinkYourSkill agent SDK.
+ *
+ * Response shapes mirror the REST agent API (`/api/agent/*`, see
+ * api/src/routes/agent.ts) and the MCP tool contract (mcp-server/src/tools).
+ * Fields are intentionally permissive ([key: string]: unknown) so the SDK
+ * keeps working when the API adds non-breaking fields.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@linkyourskill/mcp-client",
+  "version": "0.1.0",
+  "description": "Official TypeScript/Node.js SDK for the LinkYourSkill agent API — search Skillanbieter, prepare orders, and track status from AI agents.",
+  "keywords": [
+    "linkyourskill",
+    "mcp",
+    "ai-agent",
+    "marketplace",
+    "sdk",
+    "skillanbieter"
+  ],
+  "homepage": "https://linkyourskill.ai/docs/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linkyourskill-ai/linkyourskill.ai.git",
+    "directory": "sdk"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}