@zzish/sdk-js

JavaScript SDK for the legacy Zzish / Quizalize API.

This package is the canonical source for the shared zzish.js client used by Quizalize services. It supports both current server-side CommonJS usage and legacy browser pages that expect a global window.zzish object.

Consumers

Current active consumers should depend on this package through npm:

• quizalize
• quiz-player
• quiz-player-v2
• spitafields

Some older applications still serve /lib/zzish.js directly in the browser. Those files must be generated from this package or checked against this package by CI. They must not become independent source files.

Supported module shapes

CommonJS:

const zzish = require("@zzish/sdk-js");
zzish.init({ api: "APP_ID", baseUrl: "api.quizalize.com/" });

Browser global:

<script src="/lib/zzish.js"></script>
<script>
  window.zzish.init({ api: "APP_ID" });
</script>

Important compatibility contracts

These behaviours are covered by tests and should not be changed casually:

• postContent(profileId, type, uuid, meta, tags, content, callback) remains supported for legacy 7-argument callers.
• postContent(profileId, type, uuid, meta, content, callback) remains supported for modern 6-argument callers and must not overwrite existing tags.
• stopActivityWithObjects(activityId, parameters, callback) preserves parameters.activityDefinition.type; this avoids null xAPI definition types hitting strict Spring Data 4 finder behaviour in zzish-api.
• logActions supports both legacy 4-argument and modern 5-argument forms.
• Node/CommonJS import must work without relying on each consumer app to declare this package's runtime transport dependency.

Development

Install dependencies:

npm install

Run contract tests:

npm test

Check package contents before publishing:

npm pack --dry-run

Publishing rule

Do not republish an existing version. Bump the package version for every SDK change, publish to npm, then update consumers one at a time with their lockfiles and smoke tests.

Rollback is a consumer-side package pin revert. Do not unpublish or overwrite a published npm version.