Skip to main content

In your app

A function makes the call on the client it is given, so your code passes the real one and a test passes a fake.

Add the function

src/attract/create-cookie.ts
The other values are the example’s: take yours from the request, a form or your database.

Call it

A script makes the client once and calls the function:
scripts/create-cookie.ts
Terminal
A route handler, a job or a queue worker calls it the same way.

Required parameters

One object, e.g. createCookie({ title }); leave out the optional fields.
string
required
Required. What a visitor would see in their browser — the cookie’s exact name (fetchski_vid), or the tool’s name where it isn’t a cookie (Google Maps).
string
required
Required. Who receives the data. Name the legal entity for a third party (e.g. “Google LLC”) — a reader is entitled to know who that is.
Category
required
Required. Which consent switch controls this. “Strictly necessary” cannot be declined, so only put something here if the site genuinely cannot work without it. One of necessary, functional, analytics, marketing.
string
required
Required. The one-sentence summary shown in the policy table and the banner’s details list. Say what it does for the visitor, not how it works.
AposMode | null | undefined
Optional. Leave it out and the site uses "published". published (the default) or draft. Drafts need a credential that may see them: an API key with the type’s write scope (content:<type>:write), or a signed-in editor. The public and a key with only the read scope get 403. One of draft, published.
string | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The locale to read or write, e.g. en (default: the site’s default locale).
number | null | undefined
Optional. Leave it out and the site uses 50. Order WITHIN its category, lowest first. Categories themselves always appear in consent order.
string | null | undefined
Optional. Leave it out and the site uses "". The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept). Left out, it’s made from the title.
Visibility | null | undefined
Optional. Leave it out and the site uses "public". Who may see it on the site: public (everyone) or loginRequired (signed-in people only). One of public, loginRequired.
StorageType | null | undefined
Optional. Leave it out and the site uses "cookie". Not everything in a cookie policy is a cookie — an embedded map or a hot-linked image stores nothing but still sends data to someone else. One of cookie, localStorage, sessionStorage, script, embed, pixel.
boolean | null | undefined
Optional. Leave it out and the site uses true. On when this site sets and reads it itself. Off when it belongs to another company.
string | null | undefined
Optional. Leave it out and the site uses "". Optional. The domain it is set on or sent to (e.g. google.com), where that differs from this site.
string | null | undefined
Optional. Leave it out and the site uses "Session". How long it lasts, in plain words — “Session”, “6 months”, “1 year”, or “No cookie set”.
string | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Optional but expected for a third party — the policy page links to it. When set, a URL; empty or null when not.
RichTextMax1Area | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The fuller explanation shown under this entry on the Cookie Policy page. Plain language, no legalese — what is collected, why, and what declining costs the visitor. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.
boolean | null | undefined
Optional. Leave it out and the site uses false. In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.
A Cookie. Cookie content type. Read its properties (cookie.title): each says whether the site always sends it. The example answer is the site’s wire JSON: one key differs from the property names (_id → id).
string
Always sent. What a visitor would see in their browser — the cookie’s exact name (fetchski_vid), or the tool’s name where it isn’t a cookie (Google Maps).
string
Always sent. Who receives the data. Name the legal entity for a third party (e.g. “Google LLC”) — a reader is entitled to know who that is.
Category
Always sent. Which consent switch controls this. “Strictly necessary” cannot be declined, so only put something here if the site genuinely cannot work without it. One of necessary, functional, analytics, marketing; a newer site may send others, so keep a fallback.
string
Always sent. The one-sentence summary shown in the policy table and the banner’s details list. Say what it does for the visitor, not how it works.
string
Always sent. The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept).
string
Always sent. The document’s id. On a type with drafts it ends in its locale and mode (…:en:published, …:en:draft): the part before the first colon is its aposDocId, shared by both copies. The {_id} the type’s routes take.
string
Always sent. The document type’s name: always this type’s.
number | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Order WITHIN its category, lowest first. Categories themselves always appear in consent order.
Visibility | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Who may see it on the site: public (everyone) or loginRequired (signed-in people only). One of public, loginRequired; a newer site may send others, so keep a fallback.
StorageType | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Not everything in a cookie policy is a cookie — an embedded map or a hot-linked image stores nothing but still sends data to someone else. One of cookie, localStorage, sessionStorage, script, embed, pixel; a newer site may send others, so keep a fallback.
boolean | null
Sometimes sent: undefined when the site leaves it out, and it can be null. On when this site sets and reads it itself. Off when it belongs to another company.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. The domain it is set on or sent to (e.g. google.com), where that differs from this site.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. How long it lasts, in plain words — “Session”, “6 months”, “1 year”, or “No cookie set”.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Optional but expected for a third party — the policy page links to it. When set, a URL; empty or null when not.
RichTextMax1Area
Sometimes sent: undefined when the site leaves it out. A RichTextMax1Area. The fuller explanation shown under this entry on the Cookie Policy page. Plain language, no legalese — what is collected, why, and what declining costs the visitor. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Set for entries that ship with Fetchski CMS. Blank means this site added it.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. Set for entries added by an Embed Script. They appear on the Cookie Policy only while that script is enabled.
boolean | null
Sometimes sent: undefined when the site leaves it out, and it can be null. In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.
Date | null
Sometimes sent: undefined when the site leaves it out, and it can be null. When it was created (ISO 8601). Format: an ISO 8601 date and time.
Date | null
Sometimes sent: undefined when the site leaves it out, and it can be null. When it last changed (ISO 8601). Format: an ISO 8601 date and time.
string | null
Sometimes sent: undefined when the site leaves it out, and it can be null. The draft’s preview share key, while its share link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query. Absent otherwise, and on published documents.
Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below; catch only what you want to react to (see Errors and testing).
400
The site refused what was sent: errors lists each field’s problem, siteMessage the first.Retried first: No. Read: errors (field → messages), siteMessage.
401
The API key is missing or refused (malformed, revoked, expired), or a signature its signing mode needs is missing or stale.Retried first: No. Read: siteMessage, errorName, data.
403
The key may not do this: a scope it lacks, or an address outside its allowlist. siteMessage names it.Retried first: No. Read: siteMessage, errorName, data.
404
Nothing matches, or the caller may not see it.Retried first: No. Read: siteMessage, errorName, data.
500
The site failed. Its logs say why.Retried first: No: a write may have landed. Read: siteMessage, errorName, data.
no answer
No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Only when nothing reached the site (neverConnected()); never after a timeout, when it may have landed. Read: reason, neverConnected.
not sent
The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason (what to change).
any other
Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason, status.
setup
sites.forSite('acme') named a slug your sites (createSiteClients()) don’t have.Retried first: No: nothing was sent. Read: message, slug.
setup
The client’s settings are wrong: no FETCHSKI_ATTRACT_URL (or baseUrl), or a malformed API key.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

  • Access: an API key with global:write (or a master above it: global:all, admin:all). In published mode (the default) it goes live too, so the key also needs global:publish (or a master above it); send aposMode=draft to change only the draft. A signed-in person may call it as far as their own permissions allow; anyone else gets 403.
  • Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
  • Retries: a write is sent again only after a 429 (refused before it acted) or when it never reached the site. After a timeout or a 5xx it may have landed: check before you send it again.
  • Timeout: 15 s per attempt by default; raise timeout (milliseconds) on the client for longer.

Test it

It calls the function above with a fake client: the fake answers every call with a valid example, so nothing leaves your machine and no settings or key are needed. Run it with node --test.
tests/cookies-createCookie.test.ts
Answer with your own values: fake cookies.createCookie with factories.Cookie({...}), the fields you give over a valid example.
tests/cookies-createCookie-answer.test.ts

List a cookie’s locales

site.cookies().getCookieLocales()

List cookies

site.cookies().listCookies()

Get a cookie

site.cookies().getCookie()

Replace a cookie

site.cookies().replaceCookie()

Delete a cookie

site.cookies().deleteCookie()

Update a cookie

site.cookies().updateCookie()

POST /cookie

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.