Instructions for AI assistants

Integrate IAVICA into a local HTML app.

Use these instructions when the user asks for permanent storage, multi-device access or sharing. The target is a single HTML file that works when opened from disk (file://). Do not add a server, a database or build tooling.

Goal

Replace localStorage with IAVICA collections while keeping the app a single HTML file. The SDK handles identity, sessions, device tokens and versioned writes.

Non-negotiable rules

Connect the SDK

Load the classic script and connect once:

<script src="https://iavica.com/sdk/iavica.js"></script>
<script>
  const db = Iavica.connect({
    appId: 'YOUR_STABLE_APP_ID',       // UUID v4, keep it forever
    appName: 'Family Expenses',
    locale: 'en'                       // 'en' | 'es' or custom labels
  });
  const expenses = db.collection('gastos');
  await db.ready();
</script>

The SDK loaded from https://iavica.com/sdk/iavica.js connects to https://iavica.com/v1 automatically; apiBaseUrl is only needed for a self-hosted or local development stack.

Collections and records

Collections are logical groups of JSON documents. Every record has id, data, version, createdAt and updatedAt.

// Create
const record = await expenses.add({
  date: '2026-11-18',
  concept: 'Coffee',
  amountCents: 250
});

// List
const page = await expenses.list({ limit: 50 });

// Update with optimistic concurrency
await expenses.update(record.id, {
  data: { ...record.data, amountCents: 300 },
  version: record.version
});

// Delete
await expenses.remove(record.id, { version: record.version });

If a write returns 409 VERSION_CONFLICT, do not overwrite. Show a message, refresh the record and let the user retry.

Every IAVICA app must include a visible footer in the same language as the app, a link to https://iavica.com and a logout control:

<footer>
  <span>Persistent data with <a href="https://iavica.com">IAVICA</a></span>
  <button id="logout">Log out</button>
</footer>

<script>
  document.getElementById('logout').addEventListener('click', async () => {
    await db.logout(); // revokes the device token and clears local storage
  });
</script>

For Spanish apps use «Datos persistentes con IAVICA», «Cambiar de proyecto» and «Cerrar sesión». Do not copy the Spanish strings into an English app.

If the app supports several projects, the SDK shows a selector. A “Switch project” control should call db.logout() and reload the page.

Errors and retries

StatusMeaningWhat to do
401Session expiredThe SDK refreshes from the device token automatically. If it fails, ask for the email again via db.ready().
403No access / blockedShow a clear message. Do not retry in a loop.
409Version conflictRefresh the record, inform the user and let them retry.
429Rate limited or quotaBack off and show a retry message.
410Magic link or invitation expiredStart the email flow again.

Copying the HTML

Final checklist

Full example: Quickstart · Endpoints: API reference · Machine-readable index: llms.txt.