Upgrading from 0.1.0

@joinmarka/sdk 0.2.0 brings the SDK back in step with the current Marka API. Several request and response fields were renamed on the server after 0.1.0 shipped, and the server no longer accepts the old names, so a 0.1.0 client that sends them is rejected with a 400. Upgrade the package and rename the fields below. The same list is in the package's CHANGELOG.md, which ships inside it.

npm install @joinmarka/sdk@0.2

While the version is below 1.0, a minor release may contain breaking changes; they are always listed here and in the changelog under "Breaking". Nothing else about MarkaClient changed: the same methods, URLs, headers and error classes. The marka-mcp-stdio command and the other MCP tools are also unchanged.

Requirements

This is a clarification, not a change. MarkaClient runs on Node.js 20.19 or newer. @joinmarka/sdk/mcp and the marka-mcp-stdio command need Node.js 22.13 or newer, which is a requirement of @mastra/core. The same was true of 0.1.0; the package's engines field (>=20.19.0) describes the client only.

Breaking changes

categoryId is now categoryPath

createListing takes categoryPath, a slash-separated lowercase path. It is never an external marketplace's numeric category id. The server rejects the old categoryId key. Omitting it still defaults to "general".

// 0.1.0
await marka.createListing({ title, description, price, categoryId: "electronics/cameras" });

// 0.2.0
await marka.createListing({ title, description, price, categoryPath: "electronics/cameras" });

Listings in responses carry categoryPath in place of categoryId.

attributesJson is now attributes

Same method, same migration: rename the key. The value is unchanged. Listings in responses carry attributes in place of attributesJson.

// 0.1.0
await marka.createListing({ title, description, price, attributesJson: { brand: "Canon" } });

// 0.2.0
await marka.createListing({ title, description, price, attributes: { brand: "Canon" } });

Order fields lose the Json suffix

Code that reads the old names gets a type error and, at runtime, undefined.

// 0.1.0
const price = order.priceSnapshotJson;

// 0.2.0
const price = order.priceSnapshot;

checkoutShippingDetails is a typed object

It is null or { name, email, phone, address: { line1, line2, city, state, postal_code, country } }, where every field is a string or null. Narrowing code written against the old untyped JSON value can be removed; code that cast it to its own shape should switch to the exported type.

// 0.1.0
const to = order.checkoutShippingDetailsJson as { address?: { city?: string } } | null;

// 0.2.0
const city = order.checkoutShippingDetails?.address.city;

Three order statuses were removed

seller_cancelled, delivery_issue and resolved are no longer valid values for the status filter on listOrders or for the status of an order. The server never produced them, so no real order carries one, but code that names them fails to type-check: delete those branches or filter values. Dispute resolved is a different field and is unchanged.

// 0.1.0
await marka.listOrders({ status: "delivery_issue" });

// 0.2.0: pick one of the statuses that exist, for example
await marka.listOrders({ status: "dispute_open" });

The create_listing MCP tool takes categoryPath

This is the SDK's local MCP server and the marka-mcp-stdio command. Tool inputs are strict, so an agent or saved prompt that still sends categoryId gets a validation error. Update the prompt or the call.

{ "title": "Canon AE-1", "description": "Works.", "price": 18000, "categoryPath": "electronics/cameras" }

The listing MCP tools validate before calling the API

A title over 200 characters is rejected, and a categoryPath must be lowercase letters and digits separated by - or /. Callers that sent longer titles or other shapes were already getting a 400 from the server; they now get the error from the tool instead.

New in 0.2.0

• getMcpOAuthServerConfig() (from @joinmarka/sdk/mcp) returns an MCP client configuration for the hosted gateway with no API key in it. The client signs in through the browser and holds a short-lived token that the account owner can revoke from Settings. Keep using getMcpServerConfig for scripts and CI, where there is no browser. See the SDK guide.
• The MCP configuration types are exported from the package root as types only, so importing them does not pull the MCP server into a browser bundle.
• madeInCountry is a listing field: an ISO 3166-1 alpha-2 country code such as "CA", or null. You can set it on createListing and updateListing; null clears it on an update. The hosted MCP server's listing tools (/api/mcp) accept it too; the SDK's local create_listing and update_listing tools do not yet. It is the item's country of manufacture, and Marka sends it with international shipping rate requests.
• The changelog ships inside the package.

Other changes

• @mastra/core is pinned to 1.68.0 (was 1.40.0), @mastra/mcp to 1.18.0 (was ^1.9.1) and zod to 4.6.5 (was 4.3.6). The pins are exact. If your project also depends on these packages, align your versions with these so your package manager installs one copy of each.
• Importing MarkaClient from @joinmarka/sdk no longer loads zod, so browser and extension bundles that use only the client stay small. The MCP server remains available from @joinmarka/sdk/mcp only.
• A quadratic-time pattern in the base URL cleanup was replaced with a linear one. A baseUrl ending in a very long run of / characters could keep the process busy for a long time; the resulting URL is identical. This only matters if an untrusted value can reach baseUrl.