SDK
@joinmarka/sdk — a typed TypeScript client for /api/v1, plus a local MCP server built on top of it.
@joinmarka/sdk is a thin, typed client for Marka's public API. Its request and response types come
from the same contract that generates the API reference, so the SDK cannot describe an
endpoint the API does not have.
npm install @joinmarka/sdkThis guide is for the 0.2 releases. Coming from 0.1.0? Several request and response fields were renamed and the server no longer accepts the old names, so read Upgrading from 0.1.0 first.
ESM only. 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 package's engines field (>=20.19.0) describes the client only. The package is published from
DevinoSolutions/marka-node, which carries the built
artifact; the source lives in the Marka monorepo.
Quickstart
import { MarkaClient } from "@joinmarka/sdk";
const marka = new MarkaClient({ apiKey: process.env.MARKA_API_KEY! });
const { user, plan } = await marka.getMe();
console.log(`${user.email} — ${plan.tier}`);
const { results } = await marka.search({ q: "road bike", limit: 5 });
for (const listing of results) {
// Integer minor units — the SDK converts nothing.
console.log(listing.title, listing.price, listing.currency);
}Configuration
new MarkaClient({
apiKey: "mk_…",
baseUrl: "http://localhost:3001", // optional
fetch: myFetch, // optional, injectable transport
});baseUrl is an origin
baseUrl is scheme and host only. The /api mount point and the /v1/… path are appended by
the client. Passing https://joinmarka.com/api or .../api/v1 produces a doubled path that
404s. It defaults to https://joinmarka.com; override it to develop against a local web app.
Configuration is constructor arguments only — the SDK never reads process.env, so the same
instance is safe in a browser, a worker, or a multi-tenant server.
Methods
One method per operation, named for the operation id.
| Method | Endpoint |
|---|---|
getMe() | GET /v1/me |
listListings(query?) | GET /v1/listings |
createListing(body) | POST /v1/listings |
getListing(id) | GET /v1/listings/{id} |
updateListing(id, body) | PATCH /v1/listings/{id} |
publishListing(id) | POST /v1/listings/{id}/publish |
search(query?) | GET /v1/search |
listCategories(query?) | GET /v1/categories |
listOrders(query?) | GET /v1/orders |
getOrder(id) | GET /v1/orders/{id} |
The client is deliberately thin: it does not re-validate responses. The contract schemas are its compile-time types, and the server has already validated what it sent.
Creating a listing
const { listing } = await marka.createListing({
title: "Trek road bike, 56 cm", // 1 to 200 characters
description: "Light use, new tyres.",
price: 45000, // integer minor units: CA$450.00
currency: "CAD",
categoryPath: "sports/cycling", // lowercase, slash-delimited; never an external category id
attributes: { frameSizeCm: 56 }, // any JSON value
madeInCountry: "CA", // ISO 3166-1 alpha-2, or null
pickupEnabled: true,
directEnabled: true,
});
await marka.updateListing(listing.id, { price: 42000, madeInCountry: null });Only title, description and price are required. categoryPath defaults to "general" and
must be lowercase letters and digits separated by - or /. madeInCountry is accepted in
lowercase and stored uppercase; an unknown code is a 400. On an update, null clears it and
omitting it leaves it unchanged. Both methods reject keys they do not know with a 400 that names
the key, so a 0.1.0 field name fails loudly rather than being ignored.
updateListing takes title, description, price, imageUrls, madeInCountry and the four
pickupEnabled, shippingEnabled, directEnabled, checkoutEnabled flags. It does not take
categoryPath or attributes. A listing in the response carries categoryPath, attributes and
madeInCountry.
Reading an order
const { orders } = await marka.listOrders({ status: "shipped" });
for (const order of orders) {
order.listingSnapshot; // the listing as it was when the order was placed
order.priceSnapshot; // the price breakdown, integer minor units
const to = order.checkoutShippingDetails; // null, or the typed object below
if (to) console.log(to.name, to.address.city, to.address.postal_code);
}checkoutShippingDetails is null or { name, email, phone, address: { line1, line2, city, state, postal_code, country } }, where every field is a string or null. It is the buyer's contact
details, so handle it as personal data.
Errors
Failures are thrown, never returned, so a caller who only writes the happy path cannot silently proceed on a failed request. There are two error types:
import { MarkaApiError, MarkaNetworkError } from "@joinmarka/sdk";
try {
await marka.createListing({ title: "…", description: "…", price: 4500 });
} catch (error) {
if (error instanceof MarkaApiError) {
// The API answered and said no. `status` and `code` are what you branch on.
if (error.status === 402 && error.code === "entitlement_required") {
console.error("This plan cannot write through the API. Upgrade to Pro.");
} else if (error.status === 429) {
console.error("Rate limited — pause for a minute.");
}
} else if (error instanceof MarkaNetworkError) {
// No answer at all: DNS, TLS, timeout, aborted socket. Usually worth retrying.
// The original failure is preserved on `error.cause`.
}
}MarkaApiError.message is the envelope's error string verbatim. MarkaApiError.code is the
optional refinement — branch on status first.
One code is raised by the SDK rather than the server: invalid_response, for a 2xx whose body is
not JSON at all. It carries the response's own status, because the API did answer — it just did not
answer with the contract. In practice this means a proxy, an error page, or a truncated body wearing
a 200.
The stdio bridge
@joinmarka/sdk ships marka-mcp-stdio, a bridge for clients that can only start a local process.
It is a proxy of the hosted gateway: it lists whatever https://joinmarka.com/api/mcp
lists for your API key, with the same permission tiers, confirmation steps and denials.
import { startMarkaStdioProxy } from "@joinmarka/sdk/mcp";
await startMarkaStdioProxy({ apiKey: "mk_…" });The package ships a ready-made bin that does exactly this and runs under plain Node:
npx -p @joinmarka/sdk marka-mcp-stdio --helpSee Claude Desktop for how to wire it into a client.
From a checkout
Working on the SDK itself rather than using it? Inside the monorepo the package is a workspace
dependency that exports TypeScript source directly — no build step, and dist/ is not used by
anything internal. The bridge runs through tsx:
node packages/sdk/bin/mcp-stdio.mjs --api-key=mk_… --base-url=http://localhost:3001The published artifact is a different shape: pnpm release:sdk compiles the package with tsup
(bundling the internal @marka/shared contract types into it), assembles a publish-time
package.json pointing at dist/, and pushes the result to the marka-node repo, whose GitHub
release triggers the npm publish. Bump version in packages/sdk/package.json to cut a release.