@silo-software/sdk

Framework-independent Silo SDK. The package contains compiled JavaScript and declarations; it has no Silo database, transactions, auth, Redis or provider dependencies. React components and hooks live in @silo-software/react, Next.js helpers in @silo-software/next.

• @silo-software/sdk: HTTP client, DTO schemas and CmsApiError.
• @silo-software/sdk/types: runtime-validated delivery schemas and inferred TypeScript types.
• @silo-software/sdk/pdf-regions: issue PDF region geometry schemas.
• @silo-software/sdk/server: server-only cryptographic and bounded-body helpers; never import in a browser bundle.

import { createCmsClient } from '@silo-software/sdk';
const cms = createCmsClient({ baseUrl: 'https://api.example.com', clientId: 'cms_registered_client', publicApiKey: 'site_public_key' });
const capabilities = await cms.getCapabilities();
const article = await cms.getArticle('published-article');

Public keys identify a site client and enforce provider policy; they grant no draft, management or paid-content access. Requests validate responses, use bounded timeouts, refuse redirects with credentials, and disable caching on reader/preview/mutation paths. CmsApiError exposes status/code/requestId/retryAfter without echoing tokens or upstream response bodies. The survey response helper uses bounded retries with the same saved action identity; other mutation calls are not retried automatically unless a retry helper is used.

API family /public/v1 serves published projections, /reader/v1 checks the existing Billing-backed reader entitlement service, /preview/v1 requires a scoped preview grant, and /v1/sites/:siteId/preview requires an authorized tenant management principal. Browser origins must match the integration allowlist; server-to-server use needs no Origin header. HTTPS is required except explicit development HTTP connections.

Version 0.1.0 targets CMS API v1. New response fields remain additive; incompatible changes require a new API major version. The authenticated capabilities endpoint lists the implemented features. Package publication is separate from a local pack/export; this work does not publish to a registry.

Build the packages with pnpm --filter @silo-software/sdk --filter @silo-software/react --filter @silo-software/next build before starting monorepo services directly. The normal Turbo production build includes this dependency automatically. Exported consumers receive the compiled package and do not need its source or build tools.

Unkey v2 verification follows the official v2 migration contract: the API owns root credentials and the cms.public.read permission check. No root credential enters this package. Legacy hash acceptance is an explicit integration compatibility setting; it is not a fallback after a rejected managed key. Production rate and usage policies must be verified against the actual Unkey API/key configuration.

Reader token responses may include refresh_binding and refresh_expires_in. The binding is private session material and must stay out of logs, URLs and browser JavaScript. refreshToken(token, requestId?) supports a 64-character hex request identifier: use the same private identifier only for identical concurrent refresh requests. The API returns the same result for five seconds, then treats reuse as replay and revokes the reader session. Different request identifiers revoke on reuse immediately. Central account expiry/logout and explicit reader logout invalidate the new session family.

Issue PDF reader: getIssueMetadata({magazineSlug,issueSlug}) returns published title/identity only. getReaderIssue(identity,accessToken?) resolves the existing publication entitlement and returns the exact released PDF pin. getIssuePdf(identity,pin,{accessToken,range,signal}) streams that pinned release without redirects or JSON buffering. Use an HttpOnly-cookie BFF: tokens stay server-side, and each PDF/range request rechecks the current release and entitlement. This does not implement audio parity, catalogue discovery, precise PDF highlights or arbitrary asset downloads.

Company site (account URL)

getSiteShell() returns site.accountUrl, the origin of the publisher's company site that serves login, account and checkout. A client created without accountUrl uses it for getAuthorizeUrl(), resolveAccountLinks() and resolveOfferUrl(), so a site needs no extra configuration. An explicit accountUrl still takes precedence; the synchronous buildAuthorizeUrl(), getAccountLinks() and buildOfferUrl() keep requiring it.

App blocks

@silo-software/sdk/content exports splitAppContentHtml(html) for the editor's div[data-type="app-block"] blocks and resolveAppContent(client, html, { lang }), which resolves them to embed URLs through the public app API. Call it on the server with a client that has the site's server secret; blocks of apps that are not installed for the site are left out.

Survey responses and retries

Prepare one action per reader submission and persist it with the original input before sending. The descriptor contains the resolved publication, response session, operation ID, participant identity and exact payload. Reuse both values after a timeout or reload; clear them only after a confirmed result.

const input = { surveyId: 'mein-quiz', source: 'STANDALONE' as const, answers };
const action = await cms.prepareSurveyResponse(input);
await savePendingSubmission({ input, action });
try {
  const result = await cms.respondToSurvey(input, { action });
  await clearPendingSubmission();
} catch (error) {
  // Retain input and action for a later retry. CmsApiError exposes retryAfter;
  // 409 means the saved action and response cannot be changed and reused.
}
// After reload: cms.respondToSurvey(saved.input, { action: saved.action })

Without an explicit action, retrying respondToSurvey with the same input object reuses its pending action in the same SDK instance. New input objects are separate submissions, even when answers match. A CmsApiError from the request exposes the pending descriptor as recoveryAction; save it if recovery must survive a reload. The helper makes at most three attempts and honours Retry-After up to five seconds per pause. Progress and prompt-event helpers do not use this response-action retry contract.

Analytics

@silo-software/sdk/analytics exports createSiloAnalytics({ endpoint, consent, flushIntervalMs? }) for a same-origin createAnalyticsCollector route. Call page(), track(), or trackArticle({ articleId, element?, readingTimeSeconds? }); stop article tracking when leaving the article and call destroy() when finished. Update consent with setConsent(). Identity is stored only with consent.

The same entry exports the hosted-site event builder, browser queue, identity and attribution helpers, and engagement recorder. Events use the hosted-site array format; the Next collector also accepts the previous { consent, events } format.

@silo-software/sdk/recommendations exports recommendation schemas and types.

@silo-software/sdk/site exports Silo site navigation, URL, domain, sharing, article ordering and request-header helpers.

Content helpers

@silo-software/sdk/content provides Silo ad placement, media, image-alt, scholarly article, embed, and rich-text data helpers.