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/exist-in-locale.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/exist-in-locale.ts
Terminal
A route handler, a job or a queue worker calls it the same way.

Required parameters

One object, e.g. existInLocale({ ids }); leave out the optional fields.
readonly string[]
required
Required. Array of document IDs to check.
string
required
Required. Locale to check documents in.
ExistInLocaleRequestMode
required
Required. Mode to check documents in. One of draft, published.
An ExistInLocaleResponse. Document existence check completed successfully. Read its properties (existInLocale.originalLocaleIds): each says whether the site always sends it.
readonly string[]
Always sent. Array of document IDs in the original locale and mode.
readonly string[]
Always sent. Array of document IDs in the new locale.
readonly string[]
Always sent. Array of aposDocId values for the 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.
5xx
The site failed (or something in front of it did). 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

  • 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/internationalization-existInLocale.test.ts

List the site’s languages

site.internationalization().getLocales()

Get locale path and manage clipboard

site.internationalization().switchLocale()

POST /@apostrophecms/i18n/exist-in-locale

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