@clickwire/api-client

TypeScript client for our Laravel V2 API. Node 18+, server-side only — uses fetch and reads CLICKWIRE_API_URL + CLICKWIRE_TOKEN from the environment at request time (same vars as the monorepo / Next apps). No setup ceremony beyond having those set.

Use it

import { apiClient } from "@clickwire/api-client/v2";

const { data } = await apiClient.posts.list({ per_page: 20 });
const product = await apiClient.products.get("some-slug");

Prefer @clickwire/api-client/v2 over the root export when you care which API version you’re on. Methods are grouped like the HTTP API (authors, posts, products, …). Types are prefixed V2* — use them for query params and response shapes.

Optional: apiClient.configure({ locale: "nl" }) sets the global locale query param for V2. Most of the times the default locale for the Website will be sufficient.

Global query params

Configure query params once instead of repeating them on every call:

import { createV2ApiClient } from "@clickwire/api-client/v2";

const clickwire = createV2ApiClient({
    // Semantic: this website doesn't carry these product types.
    catalog: { excludeProductTypes: ["sneakers"] },

    // Generic: default query params per endpoint, keyed by `<group>.<method>`.
    defaultQuery: {
        "products.list": { per_page: 8 },
        "posts.list": { sticky: true },
    },
});

// `exclude_product_types[]=sneakers&per_page=8` sent automatically:
await clickwire.products.list({ sort: "newest" });

catalog.excludeProductTypes sends exclude_product_types[] on every catalog-surface endpoint (products.list, products.related, productAttributes.list, productAttributes.popular, productAttributes.get): excluded products disappear from hits, facets, and related results, and attribute products_count / has_products reflect the scoped catalog.

Precedence per query key: per-call > defaultQuery > catalog > locale. Arrays replace (never merge), so passing exclude_product_types: [] on a single call lifts the global exclusion for that request. Member endpoints never receive defaults (per-user credentials).

Members

Members log in with an e-mail code; a successful verify returns a member token. The website Bearer stays what it is; the member token travels in the X-Member-Token header, per call or per client instance. Server-side only — the Next.js route handler keeps it in an httpOnly cookie and never hands it to the browser.

import { apiClient } from "@clickwire/api-client/v2";

// Login: request a code, then trade it (typed, or the mail link's token) for a token.
// redirect_to is your own absolute URL on the site; the mail link is that URL + link_token.
await apiClient.member.requestLoginCode(
    { email, redirect_to: "https://www.sneakerjagers.com/en/s/slug/123?action=follow", source: "follow" },
    { visitorIp, query: { locale: "en" } },
);
const session = await apiClient.member.verifyLoginCode({ email, code }); // session.redirect_to
const fromLink = await apiClient.member.verifyLoginCode({ link_token }); // from a client-side POST on the landing page, never on the GET (mail scanners)
// -> set session.token as an httpOnly cookie; session.member, session.is_new_member, session.redirect_to

// Per call …
const me = await apiClient.member.get({ memberToken });
const settings = await apiClient.member.settings(); // size systems, preference questions, reminder types, ...
const sneakers = settings.size_types.find((type) => type.slug === "sneakers")!;
await apiClient.member.update({ sizes: { [sneakers.id]: { eu: "42 2/3" } }, preferences: { shopper_types: ["sneakerhead"] }, marketing_emails_accepted_at: true }, { memberToken });
await apiClient.member.uploadAvatar(file, "me.jpg", { memberToken });

// … or per request-scoped client. visitorIp makes Clickwire's per-IP limits per visitor, not per BFF.
const asMember = apiClient.configure({ memberToken, visitorIp });
await asMember.member.followedProducts.follow(productId); // first follow: restock (member's size, else whole product), price, release (if upcoming)
await asMember.member.followedProducts.follow(productId, { price: false }); // one switch off
const { likes_count } = await asMember.member.likedProducts.like(productId);
await asMember.member.followedAttributes.follow(brandAttributeId);
await asMember.member.reminders.create({ type: "restock", product_id, product_size_ids: [sizeId, otherSizeId], url: pdpUrl });
await asMember.member.reminders.create({ type: "price", product_id }); // fires at the website's price_drop_percent
const state = await asMember.member.productState(productId); // is_followed, followed_attribute_ids, reminders
const search = await asMember.member.savedSearches.create({ name: "Nike in 44", filters: { brand_ids: [card.brand_ids[0]], sizes: ["44"] }, frequency: "daily", url: searchPageUrl });
await asMember.member.savedSearches.markSeen(search.id); // new_product_ids empties
const mySize = await asMember.member.productFeed("my_size", { per_page: 24 }); // same response as products.list
await asMember.member.update({ notification_preferences: { saved_searches: [] }, deals_emails_accepted_at: true }); // [] = off

// By e-mail (no token): switches it on for that address, which gets a confirmation; empty 202.
await apiClient.member.reminders.createByEmail({ type: "release", product_id, lead_minutes: 60, email, url: pdpUrl });
await apiClient.member.savedSearches.createByEmail({ email, name: "Nike in 44", filters: { brand_ids: [12] } });
await apiClient.member.unsubscribe(tokenFromMailLink); // any member mail's unsubscribe link (reminder, saved search, deals)

Build one client per request in a route handler (configure({ memberToken })); never setConfig({ memberToken }) on the shared instance, it would leak across concurrent requests. A 401 whose body has code: "member_token_required" | "member_token_invalid" means the visitor's token is gone (expired, logged out, account deleted): clear the cookie. A 401 without code is the website Bearer failing. Full contract: docs/api/members.md in the Clickwire repo.

Logged out: if (isV2MemberAuthError(error)) { /* clear the cookie */ }. Refresh the cookie's max-age on every successful member call; the token slides 90 days with use.

Local development: no mail is sent yet, so get a member token from Tinker in the Clickwire repo: Member::findOrCreateForEmail(Website::firstWhere('slug', 'sneakerjagers'), '[email protected]', MemberSource::Login, 'nl')->createToken('web', ['*'], now()->addDays(90))->plainTextToken

Local testing

Include the package from local disk in your test client:

 "dependencies": {
    "@clickwire/api-client": "file:path/to/vp/packages/api-client",
  },

Every time you make a change to the api-client package locally you should build the package and then run npm install again in your test client.

Develop & publish

From packages/api-client:

npm run typecheck
npm run build

Release

Make sure you are authenciated with NPM:

npm login

Then run:

npm run release -- <version>

Replace <version> with either major, minor or patch or set your own x.x.x.