Skip to content
alzafchat / Developers

Documentation / Support

Compatibility and upgrades

Verified runtimes, framework support and upgrade boundaries.

Integration guide
On this pageSurface feature coverageUpgradingStandalone website login and API compatibilityAlzaf Pay visual alignment (2026-10-19)

Console terminology now calls provider records Merchants & teams and login records Accounts. A Service remains the connected application/tenant. provider_id, service_id, role values, key ownership and SDK/REST/realtime paths are unchanged. Monitoring inspection adds the normal Message DTO's card and attachment fields. Existing clients may ignore them; rebuild the Laravel host and Next console to display them. See ownership and role menus.

The 2026-11-02 source patches preserve existing REST paths, DTOs and database schema and add readonly ChatSession.conversationRevision for asynchronous UI guards. Rebuild all four JS packages, the versioned widget and affected host examples together to adopt navigation/draft/upload fixes; rebuild the Laravel host for failed-storage handling. No immutable package was republished. See interaction audit for precise local checks and remaining runtime gaps; these patches do not broaden the browser or host compatibility matrix.

Version 0.1.13 is prepared (all four JS packages aligned in lockstep); 0.1.5 is the latest immutable tag and 0.1.0 was the initial published private package release. Packages support workspace development, versioned archives, private GitHub npm registry installation and private Composer GitHub VCS installation, verified in independent consumers. See project status for evidence. Full production readiness remains unclaimed. Manifest ranges express intended dependencies, not every verified combination. Check project status for actual command outcomes.

CombinationDeclared boundaryVerification status
Laravel packagePHP ^8.3, Illuminate/Laravel ^12.0Implementation present; runtime checks being recorded in project status
Laravel central applicationLaravel ^12.0, Reverb ^1.12, SQLite local databaseOwn login and role-scoped account/service management implemented; deployed verification in project status
JS workspaceNode >=22, pnpm 11.19.0Node 24.19.0 detected; dependency/build outcomes in project status
React/Next.js demoNext.js ^16.0.0, React ^19.0.0, host-owned Tailwind CSS v4 + shadcn theme with @source registrationImplementation present; build/browser outcomes in project status
React package CSS precedenceAll package utilities carry the ac prefix; class-based dark:Decision 0011 build verified (0 unprefixed utilities, responsive pairs intact, no media-based dark) plus example production build; package selectors never collide with host utilities
Vue adapter/demoSeparate Vue dependency boundary; keeps dependency-free chatStyles, no Tailwind requiredBuild/browser outcomes in project status
Plain HTML / BladeVersioned browser widget; no consumer npm build requiredBuild/browser outcomes in project status
Attachment storagePrivate Laravel filesystem disk; host default unless overridden; S3 requires league/flysystem-aws-s3-v3 and PUT CORS for direct uploadsLocal-disk proxy/presigned paths covered by package feature tests (unrun PHP here); real S3 bucket behaviour and browser CORS unverified
SDK importsESM/CJS and generated TypeScript declarationsPublic exports defined; build/SSR checks in project status
LAN HTTPAPI 8000, Reverb 8085, Next 3000; reachable hostname + origin allowlistsRequires actual cross-device check; localhost checks alone insufficient
Production HTTPS, database engine, load, restore/rollbackDeployment-specificPending verification; no production-ready claim
Other-backend identity exchangeCentral server key → scoped customer/seller tokenAPI and revocation tests pass; real non-Laravel host example/load unverified

Surface feature coverage#

The shared SDK exposes identity, provider directory, conversations, message history/send/read, admin join, status updates, attachment staging/upload/ confirmation, and private-channel subscription. The React inbox exposes provider selection for customers, conversation search, status/unread badges with last-message preview, history with an earlier-page control that hides once the server reports no older history, replies, manual refresh and admin join. ChatProvider/useChat/useChatWithSeller share one session between seller buttons, a full-page ChatPanel (session prop) and a ChatPopover (shadcn Popover, mode="floating"|"inline", overridable fixed position/wrapperClassName/wrapperStyle, panel className/style, showTrigger={false} triggerless mode, and localStorage last-conversation persistence via persistKey, selection only). The Vue and plain-HTML inboxes expose provider selection for customers, history with the same earlier-availability gating, replies, manual refresh and admin join with the unchanged dependency-free styling. A headless API method does not imply a matching UI control.

Attachment support is equal across the three adapters: composer attach control, staged chips with remove, image previews, PDF download chips, attachment-only sends, and the built-in EMOJI_GROUPS picker with caret insertion. Attachment tiles render outside the message bubble in all three. Storage mode is server configuration, not a per-adapter feature: proxy works on any disk, and auto/presigned add direct-to-S3 uploads with presigned downloads and an automatic proxy fallback. Assignment/transfer UI, customer escalation controls, push/email notifications and the audit viewer are deferred. The Next workspace adds email/password login, token-revoking logout and administrative service/provider/ account management. Public self-registration and password-reset screens are absent.

Current browser version coverage is not yet established. Run chat/lifecycle checks on the intended desktop/mobile browsers before claiming their support. Source import safety is not proof of every Next.js SSR deployment mode.

Upgrading#

No published predecessor or migration path exists. The repository versions its contracts together at this stage; update SDK, adapters, widget and backend as a set. Retain lockfiles and record package/runtime versions with verification. Back up the database before migrations. Once a version is released, existing migrations must remain and schema changes use forward migrations. Breaking contracts require a release note and migration guide; do not keep undocumented old implementations as substitutes for an upgrade plan.

Service operators own authentication, authorization mappings, secure transport, database/storage backup, process supervision and deployed acceptance checks.

Standalone website login and API compatibility#

The standalone host adds an optional login account_role field and a forward email/role unique constraint; reusable package version0.1.0 is unchanged. Existing unique-email API callers omit the role, as does the standard website login. Use distinct email addresses for website accounts. Once an email belongs to multiple accounts, an API integration must supply the exact role; the normal website cannot select that shared identity. The API discriminator and forward migration remain supported for those integrations, rather than being deleted with the UI. The native operator can explicitly update its recorded owner identities to three distinct emails, retaining IDs/password/scopes and revoking prior sessions; see operator setup. Email collisions are refused. Before an older-schema rollback, resolve duplicate emails without deleting chat history. Native MySQL migration and remote-database cutover evidence must be recorded in project status; local SQLite tests do not prove that cutover.

Alzaf Pay visual alignment (2026-10-19)#

Current preview defaults use the original blue palette across React, Vue and HTML widget, retaining their upstream responsive layouts. No props, SDK protocol, identity or database contract changes. Rebuild and redistribute the matching packages/browser bundle to adopt it; previously published artifacts were not replaced. Local Next/React, Vue and HTML fixture evidence is in project status; this does not expand the supported browser or deployment matrix.