@zexsoft/fix-core
v1.14.54
Published
Official FIX Fiscal platform library for SvelteKit: the headless API client (auth and sessions, organizations, permissions, notifications, i18n) and the FIX Svelte components, from simple UI to drop-in pages.
Maintainers
Readme
@zexsoft/fix-core
Official FIX Fiscal library for SvelteKit apps built on FIX: typed API clients, login and persistent sessions, organization switching, permissions, notifications and i18n, plus the FIX Svelte components, from a button up to drop-in pages.
| Import | Contents |
|---|---|
| @zexsoft/fix-core | Headless core: FixCore, every API client, auth, i18n |
| @zexsoft/fix-core/components/…, @zexsoft/fix-core/pages/… | Svelte components and pages, imported by path (see Components) |
| @zexsoft/fix-core/vite | fixCore(), the Vite plugin every host adds |
| @zexsoft/fix-core/tailwind.css | Tailwind entry of the components |
The package ships Svelte sources, compiled by your app: the components take your app's Tailwind theme.
Components are flat by default: panels have no shadow, border or gradient. Add data-fix-glow to <body> in app.html
for the FIX look. Turn off the big page titles with initFixCore({ pageTitles: false }) when your own navigation names
the page; record pages keep theirs.
Install
npm install @zexsoft/fix-core axiosPeer dependencies: svelte 5, @sveltejs/kit 2, tailwindcss 4, vite 7 and axios. The components follow
shadcn-svelte: set it up first (its theme tokens and tw-animate-css).
latest is the production release. Pre-release builds are published as X.Y.Z-staging under the staging tag
(npm install @zexsoft/fix-core@staging) and target the FIX staging environment.
Proxy /api through your own server
Browser apps call FIX through their own origin: FixCore sends every request to /api/... on the page's host, and
your server forwards it to FIX. Session cookies then stay first-party on your domain, and no FIX credential is ever
exposed cross-site. Every proxy must:
- forward
/apiwith the path unchanged (the session cookie is scoped to/api/auth); - use
changeOrigin: true, so FIX receives its own host name; - replace the browser's
Originwith the FIX origin, after checking that it is your own origin: FIX's session endpoints accept only its ownOrigin, and this check is what keeps other sites from using your proxy; - pass FIX's responses through untouched, including
429 Too Many Requestsand itsRetry-Afterheader.
Session cookies are Secure, so production must be served over HTTPS (localhost is exempt in browsers).
Development (Vite)
// vite.config.js
import { defineConfig } from 'vite';
const FIX = 'https://go.fixfiscal.ro'; // staging: https://staging-go.fixfiscal.ro
export default defineConfig({
server: {
proxy: {
'/api': {
target: FIX,
changeOrigin: true,
configure: (proxy) =>
proxy.on('proxyReq', (req) => { if (req.getHeader('origin')) req.setHeader('origin', FIX); }),
},
},
},
});Production (Express)
import express from 'express';
import { createProxyMiddleware } from 'http-proxy-middleware';
const FIX = 'https://go.fixfiscal.ro';
const OWN_ORIGIN = 'https://app.example.com'; // your app's public origin
const app = express();
app.use('/api', (req, res, next) => {
const origin = req.headers.origin;
if (origin && origin !== OWN_ORIGIN) return res.status(403).end();
next();
});
// Express strips the mount path from req.url, so the target carries /api to keep the path unchanged.
app.use('/api', createProxyMiddleware({
target: `${FIX}/api`,
changeOrigin: true,
on: { proxyReq: (proxyReq, req) => { if (req.headers.origin) proxyReq.setHeader('origin', FIX); } },
}));
// ...serve your app, plus the UI assets (see "Assets") ...
app.listen(3000);Rate limits
FIX rate-limits its API and answers 429 with a Retry-After header (seconds). Login, password reset, invitations
and similar endpoints are limited strictly. FixCore does not retry on its own; wait Retry-After before retrying.
API clients throw an ApiException (status, headers); session calls such as login() throw an axios error
(response.status, response.headers):
/** Seconds to wait before retrying, or 0 when the error is not a rate limit. */
function retryAfter(error: any): number {
const status = error?.status ?? error?.response?.status;
const headers = error?.headers ?? error?.response?.headers;
return status === 429 ? Number(headers?.['retry-after'] ?? 60) : 0;
}
try {
await fixCore.login(email, password);
} catch (error) {
const wait = retryAfter(error);
if (wait) showMessage(`Too many attempts, try again in ${wait} s.`);
}Quick start
import { initFixCore, setLocale } from '@zexsoft/fix-core';
// Once, at app start. persistentSession keeps users signed in across reloads (cookie refresh through your proxy).
const fixCore = initFixCore({
persistentSession: true,
onUnauthorized: () => showLoginScreen(),
onNotify: ({ type, message }) => toast(type, message),
});
await fixCore.initializeSession(); // restores the previous session, if any
if (!fixCore.isAuthenticated) await fixCore.login(email, password);
console.log(fixCore.user?.email, fixCore.user?.enrollments);
// The active organization; every request carries it, and currentTenant reloads.
fixCore.organizationId = fixCore.user?.enrollments?.[0]?.id ?? null;
if (fixCore.hasPermission('FiscalEntity', 'Create')) { /* ... */ }
const partners = await fixCore.fiscalEntity.list('acme', null, null, 0, 20); // search, filter, sort, skip, limit
fixCore.logout();Elsewhere in the app, import the fixCore singleton (import { fixCore } from '@zexsoft/fix-core'). For separate,
stateless clients, use createFixClient(options) instead of the singleton.
i18n
Messages come in Romanian (ro, the default) and English (en). The locale is kept in a cookie.
import { getLocale, locales, setLocale } from '@zexsoft/fix-core';
setLocale('en'); // reloads the page in English
setLocale('en', { reload: false }); // or switch in place
fixCore.i18n.t('partners'); // 'Partners'Override or add messages with initFixCore({ translationDictionary: { partners: 'Clients' } }), either flat or per locale
({ partners: { ro: 'Clienți', en: 'Clients' } }).
API keys (server-side only)
For SvelteKit server code (+server.ts, hooks) talking to FIX without a user login, use an API key issued from the
FIX dashboard. It is sent as X-Api-Key. The core is Svelte code, compiled by your app's Vite build; a .NET backend
uses the FIX.Platform.Client NuGet package instead.
import { createFixClient } from '@zexsoft/fix-core';
const fix = createFixClient({ baseUrl: 'https://go.fixfiscal.ro', apiKey: process.env.FIX_API_KEY });Never put an API key in browser code: every visitor could read it. A browser app without a user login lets its
proxy add the key instead (headers: { 'X-Api-Key': process.env.FIX_API_KEY } in the proxy options). Everyone who can
open that app then acts with the key's permissions, so the app needs its own access control. API keys cannot call the
Auth or ApiKey endpoints, and they cannot be combined with token or persistentSession.
Components
Setup
// vite.config.ts: icons, PDF.js resources and animations, served in dev and copied into the build
import { fixCore } from '@zexsoft/fix-core/vite';
export default defineConfig({ plugins: [tailwindcss(), sveltekit(), fixCore()] });/* src/routes/layout.css, after tailwindcss and your shadcn-svelte theme */
@import '@zexsoft/fix-core/tailwind.css';<!-- src/routes/+layout.svelte -->
<script lang="ts">
import { watchBackDismiss } from '@zexsoft/fix-core/components/ui/back-dismiss/BackDismiss.svelte';
import { Toaster } from 'svelte-sonner';
// Dialogs, sheets and menus take a history entry: Back closes them instead of leaving the page.
watchBackDismiss();
let { children } = $props();
</script>
<Toaster />
{@render children()}initFixCore() runs before any component renders (a hooks.client.ts init, as in the Quick start). The package
defines no colors: components use your shadcn tokens. Its two extra tokens default to shadcn ones; set them in your
theme to override: --fix-accent (default --primary) and --sidebar-bg-accent (default --sidebar-primary).
Layers
Every file is importable by its path under components/ or pages/, in four layers:
| Layer | Path | Examples |
|---|---|---|
| UI primitives | components/ui/<name>/ | button, card, help-bubble, searchable-input, pdf-preview |
| Domain inputs and views | components/domain/<Entity>/<Entity>Input\|View.svelte | FiscalEntityType/FiscalEntityTypeInput.svelte |
| Domain forms, tables and cards | components/domain/<Entity>/… | Invoice/InvoiceDataTable.svelte, ApiKey/ApiKeyCard.svelte |
| Pages | pages/<Name>Page.svelte | AccountPage.svelte, InvoicePage.svelte |
<script lang="ts">
import { Button } from '@zexsoft/fix-core/components/ui/button/index.js';
import FiscalEntityTypeInput from '@zexsoft/fix-core/components/domain/FiscalEntityType/FiscalEntityTypeInput.svelte';
import ApiKeyCard from '@zexsoft/fix-core/components/domain/ApiKey/ApiKeyCard.svelte';
</script>Pages
Drop-in pages for SvelteKit routes. An entity page lists the entity, or shows one record when given id; route is
the route of its list (records link to ${route}/{id}), defaulting to the FIX app's.
<!-- src/routes/invoices/+page.svelte -->
<InvoicePage route="/invoices" />
<!-- src/routes/invoices/[id]/+page.svelte -->
<InvoicePage route="/invoices" id={page.params.id} />| Page | Default route | Extra props |
|---|---|---|
| AccountPage | — | docsUrl (FIX API docs, default /docs), loginRoute (default /login) |
| CompanyPage, TeamPage | — | |
| PreferencesPage | — | fixApps (FIX Fiscal app updates/downloads and version, default on) |
| InvoicePage | /invoicing/invoices, /invoicing/expenses | isReceived (expenses) |
| ItemPage, PricingRulePage, DocumentSeriesPage, ItemTagPage, ItemUnitPage | /catalog/… | |
| FiscalEntityPage, BankAccountPage, EntityBranchPage | /partners/… | |
| FiscalDayReportPage, OperatingTerminalPage, SaleChannelPage | /sales/… | rowActions (operating terminals) |
| BookingAppointmentPage, BookingTrackPage, BookingTrackTypePage, BookingTagPage, BookingOccupantTypePage | /bookings/… | |
| ReceiptPage | — | |
| DevicesPage | /devices/manage | reloadToken, filter, onClearFilters, onOpen (replaces opening the record page), toolbar, actions, emptyState |
License
MIT
