Dec 12, 2025 • 3 min read

What v1 Means for the Aiur JavaScript SDK

For Aiur, v1 is the point where SDK behavior becomes explicit: contracts, guarantees, and predictable failure.

Aiur

Aiur

Platform Engineering

What v1 Means for the Aiur JavaScript SDK

When software teams talk about a “v1,” it often means the first version that works.

For the Aiur JavaScript SDK, v1 means something more specific: it is the point at which behavior becomes explicit.

The Aiur JavaScript SDK is open source and available on GitHub:
https://github.com/aiur-io/aiur-js

SDKs are not helpers. They are infrastructure.

Client SDKs sit at the boundary between systems and reality.

They run in browsers that go offline.
They run in servers that restart.
They operate under retries, partial failures, and duplicated execution.

Despite this, many SDKs are designed as convenience layers: thin wrappers around HTTP calls that work well under ideal conditions and behave unpredictably everywhere else.

Aiur takes a different position.

SDKs are infrastructure.
And infrastructure must be defined by contracts, not assumptions.

The Aiur JS SDK is built around explicit guarantees

Before adding features, we defined what the SDK must guarantee, and just as importantly, what it must not attempt to guarantee.

In v1, the Aiur JavaScript SDK provides:

  • Explicit delivery semantics
    Events are delivered at least once within a bounded retry window.
    At-least-once means duplicates are possible, but silent loss is not.

  • Stable event identity
    Each event has a stable identifier reused across retries, enabling safe deduplication.

  • Acknowledgment-driven lifecycle
    Events are only removed after explicit acceptance by the server.

  • Offline resilience in browsers
    Events survive reloads and temporary connectivity loss when IndexedDB is available.

  • Bounded durability
    Events are intentionally dropped after configurable age or retry limits rather than persisting indefinitely.

  • Clear client/server separation
    Browser behavior, server behavior, and framework behavior are explicitly scoped.

Anything outside these guarantees is left intentionally unspecified.

This is not a limitation. It is how predictable systems are built.

Explicit behavior under failure

The most important question an SDK must answer is not “what happens when things work?”
It is “what happens when things fail?”

In Aiur v1:

  • Network failures do not create silent data loss.
  • Retries do not create duplicate side effects.
  • Reloads do not reset identity unexpectedly.
  • Non-JSON-serializable payloads are rejected locally instead of being sent ambiguously.
  • No behavior happens implicitly or “by accident.”

Failure modes are defined, bounded, and observable.

Frameworks add ergonomics, not semantics

The Aiur JS SDK is published as multiple layers:

  • A framework-agnostic core
  • A React integration
  • A Next.js integration
  • A unified entrypoint

Each layer adds convenience, not meaning.

Routing awareness exists only in the Next.js integration.
Auto-capture exists only in the React layer.
Delivery guarantees exist only in the core.

This separation ensures that behavior remains consistent across browser, server, React, and Next.js environments without leaking assumptions between them.

The SDK is published as a unified package on npm, with framework-specific layers exposed as needed:
https://www.npmjs.com/package/aiur-io

Advanced users can also consume the framework-specific packages directly.

Remote configuration without redeploys

Aiur supports server-defined SDK configuration that allows behavior to change without code changes.

This includes:

  • enabling or disabling auto-capture categories
  • applying sampling rules
  • applying selector-based filtering and redaction

Remote configuration is:

  • validated client-side
  • cached in memory only
  • safe by default
  • incapable of injecting executable logic

Configuration controls behavior toggles, not data exfiltration.

Why this matters

Most systems fail not because they lack features, but because behavior becomes implicit over time.

When behavior is implicit:

  • failures become surprising
  • debugging becomes archaeological
  • trust erodes quietly

By making v1 about contracts rather than coverage, the Aiur JS SDK establishes a stable foundation that future versions can build on without changing meaning.

v1 is not the end of the SDK.
It is the point at which its behavior became explicit enough to rely on.

A foundation, not a finish line

The Aiur JavaScript SDK v1 defines a baseline:

  • correctness over convenience
  • explicit contracts over implied behavior
  • predictable failure over silent uncertainty

Everything that follows builds on this foundation.

Further reading

Share this post