JavaScript SDK v1

<script
  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
  data-account-id="acc_YOUR_ACCOUNT_ID"
></script>

<script>
  SparkVault.products.identity.attach('.login-btn', {  // ← your login button selector
    onSuccess: async (result) => {
      await fetch('/api/auth/login', {             // ← your auth endpoint
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token: result.token })
      });
      window.location.href = '/dashboard';         // ← your success redirect
    }
  });
</script>

<script
  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
  data-account-id="acc_YOUR_ACCOUNT_ID"
></script>

<script>
  SparkVault.vaults.upload.attach('.upload-btn', {  // ← your upload button selector
    vaultId: 'vlt_YOUR_VAULT_ID',                   // ← your vault ID
    onSuccess: (result) => {
      console.log('Uploaded:', result.ingotId, result.filename);
    }
  });
</script>

// e.g. a chat attachment paperclip
fileInput.addEventListener('change', () => {
  SparkVault.vaults.upload({
    vaultId: 'vlt_YOUR_VAULT_ID',
    file: fileInput.files[0],   // skip the SDK drop-zone
    folder: 'chat/thread-42',   // optional vault sub-path, created if missing
    token: vaultAccessToken,    // optional VAT: authorize without public upload
    hideSuccessScreen: true,    // close silently when the upload finishes
    onSuccess: (result) => {
      // your app renders the "attached" UI
      addAttachmentToChat(result.ingotId, result.filename);
    },
  });
});

const health = await SparkVault.health.check();

if (!health.online) {
  console.log('SparkVault is unreachable:', health.error);
}

<script
  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
  data-account-id="acc_YOUR_ACCOUNT_ID"
></script>

npm install @sparkvault/sdk-js

import SparkVault from '@sparkvault/sdk-js';

const sparkvault = SparkVault.init({
  accountId: 'acc_YOUR_ACCOUNT_ID'
});

npm install @sparkvault/sdk-mobile

import { createSparkVaultMobileClient } from '@sparkvault/sdk-mobile';
import { SparkVaultIdentityDialog } from '@sparkvault/sdk-mobile/identity-dialog';

const client = createSparkVaultMobileClient({
  tokenStorage,
  identityAccountId: 'acc_YOUR_ACCOUNT_ID',
  identityBaseUrl: 'https://auth.sparkvault.com',
  apiBaseUrl: 'https://api.sparkvault.com/v1'
});

<SparkVaultIdentityDialog
  client={client}
  visible={visible}
  passkeyProvider={passkeyProvider}
  onCancel={() => setVisible(false)}
  onSuccess={async (result) => {
    await client.products.identity.verifyIdentityToken(result.token, { jwks: result.jwks });
    const session = await client.account.exchangeIdentityToken(result.token);
    // Continue only after local JWT verification and Core exchange succeed.
  }}
/>;

const result = await sparkvault.products.identity.signIn({
  email: 'user@example.com',  // Pre-fill email (optional)
  onCancel: () => { ... }     // Called if user closes the popup
});

// result.token - Signed JWT (verify on backend!)
// result.identity - Verified email or phone
// result.identityType - 'email', 'phone', or 'social'
// result.svid - Canonical SparkVault ID
// result.sessionId - Managed Identity session ID

// On EVERY page load: redeems a returned code or self-heals a lost popup result.
sparkvault.products.identity.handleRedirectResult({
  onSuccess: (result) => createSession(result.token),  // same handler as signIn()
}).catch((error) => showError(error));

// Boot the SDK for the return leg ONLY when a sign-in needs completing.
if (SparkVault.isRecoveryPending()) {
  SparkVault.init({ accountId: 'acc_...' })
    .products.identity.handleRedirectResult({
      onSuccess: (result) => createSession(result.token),
    }).catch(showError);
}

const cleanup = sparkvault.products.identity.attach('.login-btn', {
  onSuccess: (result) => { ... },
  onCancel: () => { ... }
});

// Later: remove click handlers
cleanup();

sparkvault.products.identity.close();

import { IdentityModule } from '@sparkvault/sdk-js';

const result = IdentityModule.isFedcmAvailable()
  ? await sparkvault.products.identity.signInWithFedcm()
      .catch(() => sparkvault.products.identity.signIn())
  : await sparkvault.products.identity.signIn();

// Manage this site (block, notifications, etc.)
window.location.href = sparkvault.products.identity.portalUrl({ section: 'sites' });

// Open the security screen
const url = sparkvault.products.identity.portalUrl({ section: 'security' });

const claims = sparkvault.products.identity.decodeToken(result.token);
console.log(claims.svid, claims.exp);

{
  "iss": "https://auth.sparkvault.com/acc_xxx",
  "sub": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "aud": "acc_xxx",
  "jti": "0192f3a1-7c4e-7b21-b3d4-9a8e6f5c2d10",
  "identity": "user@example.com",
  "identity_type": "email",
  "method": "otp_email",
  "verified_at": 1703977200,
  "svid": "ing_019e66a4e27875f2822ede0e4f5d8792",
  "session_id": "sess_abc123",
  "iat": 1703977200,
  "exp": 1703977500
}

const result = await sparkvault.vaults.upload({
  vaultId: 'vlt_abc123',
  target: '#container',  // Render inline instead of modal (optional)
  onProgress: (p) => console.log(p.percentage + '%')
});

// result.ingotId - Uploaded file ID
// result.filename - Original filename
// result.sizeBytes - File size

{
  bytesUploaded: 52428800,
  bytesTotal: 104857600,
  percentage: 50,
  phase: 'uploading'  // 'uploading' | 'ceremony' | 'complete'
}

const cleanup = sparkvault.vaults.upload.attach('.upload-btn', {
  vaultId: 'vlt_abc123',
  onSuccess: (result) => { ... }
});

cleanup(); // Remove handlers

// Create a vault. Save the VMK!
const vault = await sparkvault.vaults.create({ name: 'My Vault' });

// Unseal to get a short-lived Vault Access Token (VAT).
// The returned object is passed to ingots/folders calls.
const unsealed = await sparkvault.vaults.unseal(vault.id, vault.vmk);

// Inspect, rename, seal
const detail = await sparkvault.vaults.get(vault.id);
await sparkvault.vaults.update(vault.id, { name: 'Renamed' });
await sparkvault.vaults.seal(vault.id);

// List vaults — paginated: returns a page { vaults, nextCursor }.
// Follow nextCursor to fetch subsequent pages.
const page = await sparkvault.vaults.list();
page.vaults.forEach((v) => console.log(v.name));

// Delete requires the vault's exact name as confirmation (sent as the
// X-Confirm-Name header, case-sensitive) — not the VMK.
await sparkvault.vaults.delete(vault.id, vault.name);

const config = await sparkvault.vaults.getSharingConfig(vault.id);

await sparkvault.vaults.enableSharing(vault.id, vault.vmk, {
  allIngotsPublic: false,
  sessionLengthSeconds: 3600,
});
await sparkvault.vaults.updateSharingConfig(vault.id, { sessionLengthSeconds: 7200 });
await sparkvault.vaults.disableSharing(vault.id);

const upload = await sparkvault.vaults.getUploadConfig(vault.id);

await sparkvault.vaults.enableUploadPortal(vault.id, vault.vmk);
await sparkvault.vaults.disableUploadPortal(vault.id);
await sparkvault.vaults.enableUploadWidget(vault.id, vault.vmk);
await sparkvault.vaults.disableUploadWidget(vault.id);
await sparkvault.vaults.updateUploadConfig(vault.id, {
  maxSizeBytes: 1048576,
  notificationEmail: 'ops@example.com',
});

const retention = await sparkvault.vaults.getAccessLogRetention(vault.id);
await sparkvault.vaults.updateAccessLogRetention(vault.id, 7776000);

const unsealed = await sparkvault.vaults.unseal(vault.id, vault.vmk);

// High-level upload: creates the session, streams over TUS, verifies finalized.
const ingot = await sparkvault.ingots.upload(unsealed, {
  file: myFile,
  name: 'document.pdf',
  onProgress: (uploaded, total) => console.log(uploaded / total),
});

// High-level download: fetches a fresh signed link and returns a Blob.
const blob = await sparkvault.ingots.download(unsealed, ingot.id);

// Discrete primitives: drive the transfer yourself.
const session = await sparkvault.ingots.createUpload({
  vault: unsealed, name: 'big.zip', contentType: 'application/zip', sizeBytes: file.size,
});
const link = await sparkvault.ingots.createDownloadLink(unsealed, ingot.id);

await sparkvault.ingots.rename(unsealed, ingot.id, 'renamed.pdf');
await sparkvault.ingots.move(unsealed, ingot.id, 'fld_xyz');   // null = vault root
await sparkvault.ingots.replace(unsealed, ingot.id, { file: newFile });
await sparkvault.ingots.delete(unsealed, ingot.id);

const meta = await sparkvault.ingots.get(unsealed, ingot.id);
const { ingots } = await sparkvault.ingots.list(unsealed);
const found = await sparkvault.ingots.search(unsealed, { q: 'invoice' });
const contents = await sparkvault.ingots.listContents(unsealed, { folderId: 'fld_xyz' });

await sparkvault.ingots.updateSharingConfig(unsealed, ingot.id, { shared: true, visibility: 'invite_only' });
const sharing = await sparkvault.ingots.getSharingConfig(unsealed, ingot.id);

// Optional 4th arg: invite lifetime (omit to inherit the link's existing expiry)
const invite = await sparkvault.ingots.addInvite(unsealed, ingot.id, 'user@example.com', { expiresInSeconds: 86400 });
await sparkvault.ingots.revokeInvite(unsealed, ingot.id, invite.id);

const { logs } = await sparkvault.ingots.getAccessLogs(unsealed, ingot.id, { limit: 100 });

const unsealed = await sparkvault.vaults.unseal(vault.id, vault.vmk);

const folders = await sparkvault.folders.list(unsealed);
const folder = await sparkvault.folders.create(unsealed, { name: 'Invoices' });
const detail = await sparkvault.folders.get(unsealed, folder.id);
const trail = await sparkvault.folders.getBreadcrumb(unsealed, folder.id);

await sparkvault.folders.update(unsealed, folder.id, { name: 'Renamed' });
await sparkvault.folders.move(unsealed, folder.id, 'fld_parent');  // null = vault root
await sparkvault.folders.togglePin(unsealed, folder.id, true);
await sparkvault.folders.moveIngot(unsealed, 'ing_abc', folder.id); // null = vault root
await sparkvault.folders.delete(unsealed, folder.id);

const spark = await sparkvault.sparks.create({
  payload: 'top secret',
  ttlMinutes: 60,             // defaults to 1440 (24h)
  contentType: 'text/plain',  // optional MIME type (base64 payload for binary types)
  filename: 'note.txt',       // optional, for file payloads
});

// Kindling groups related sparks into a family
const first = await sparkvault.sparks.create({ payload: 'one', withKindling: true });
const sibling = await sparkvault.sparks.create({ payload: 'two', kindling: first.kindling });

const { sparks } = await sparkvault.sparks.list();       // filters: { kindling, status, limit, cursor }
const revealed = await sparkvault.sparks.get(spark.id);  // burns the spark
await sparkvault.sparks.delete(spark.id);

// Share via a public x.sv link
const share = await sparkvault.sparks.share(spark.id, { visibility: 'public' });
console.log(share.shareUrl);   // https://x.sv/...

const status = await sparkvault.sparks.getShare(spark.id);
await sparkvault.sparks.unshare(spark.id);

// Formatted output: hex | base64 | base64url | alphanumeric | alphanumeric-mixed | password | numeric | uuid | bytes
const { value } = await sparkvault.entropy.generate({ bytes: 32, format: 'hex' });

// Raw bytes as a Uint8Array
const key = await sparkvault.entropy.generateBytes(32);

// Page the inbox (newest first). Views: all | unseen | unread | archived (default all).
const { notifications, cursor } = await sparkvault.notify.getInbox({ state: 'unread', limit: 50 });
// A page can come back SHORT of limit yet still carry a non-null cursor — always follow the cursor.

// Bounded unseen badge count; `capped` true means render "N+".
const { unread_count, capped } = await sparkvault.notify.getUnreadCount();

// Mark one of your rows seen | read | archived (idempotent). `createdAt` MUST be the row's own
// created_at, round-tripped from the list row — the id alone cannot address the row.
await sparkvault.notify.markState(row.notification_id, { createdAt: row.created_at, state: 'read' });

if (sparkvault.notify.isWebPushSupported()) {
  const registration = await navigator.serviceWorker.register('/sw.js');
  const { status } = await sparkvault.notify.subscribeWebPush({ serviceWorkerRegistration: registration });
  // status: 'subscribed' | 'already_subscribed' | 'not_supported' | 'not_configured' | 'permission_denied'

  // Later, to turn it off on this device:
  await sparkvault.notify.unsubscribeWebPush({ serviceWorkerRegistration: registration });
}

const result = await sparkvault.health.check({
  timeout: 5000
});

// result.online - true when the API returns 2xx
// result.status - 'healthy' | 'unhealthy' | 'unreachable'
// result.httpStatus - HTTP status when a response was received
// result.checkedAt - Unix timestamp
// result.error - network/timeout message when unreachable

const online = await sparkvault.health.isOnline({ timeout: 5000 });

try {
  const result = await sparkvault.products.identity.signIn();
} catch (error) {
  switch (error.code) {
    case 'user_cancelled':
      // User closed the popup (not an error)
      break;
    case 'validation_error':
      console.error('Invalid input:', error.message);
      break;
    case 'network_error':
      console.error('Network error');
      break;
    case 'timeout_error':
      console.error('Request timed out');
      break;
    default:
      console.error('Error:', error.message);
  }
}

const sparkvault = SparkVault.init({
  accountId: 'acc_YOUR_ACCOUNT_ID',  // Required
  backdropBlur: true,                 // Blur background on modals (default: true)
  timeout: 30000,                     // HTTP timeout in ms (default: 30000)
  preloadConfig: true                 // Preload config for instant modals (default: true)
});

import SparkVault, {
  SparkVaultConfig,
  VerifyOptions,
  VerifyResult,
  UploadOptions,
  UploadResult,
  UserCancelledError,
  ValidationError,
  PlanRequiredError,
  QuotaExceededError,
  NetworkError
} from '@sparkvault/sdk-js';

const config: SparkVaultConfig = {
  accountId: 'acc_YOUR_ACCOUNT_ID'
};

const sparkvault = SparkVault.init(config);

const result: VerifyResult = await sparkvault.products.identity.signIn();

<script
  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
  data-account-id="acc_YOUR_ACCOUNT_ID"
  data-debug="true"
></script>