markaDocs

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/sdk

This 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.

MethodEndpoint
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 --help

See 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:3001

The 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.

On this page