SDKs
Libraries for TypeScript, Effect, Rust, Swift, Kotlin and Python. Each one has the same seven calls.
The libraries are open source, at github.com/snekot-co. Each installs from its repository today; they are not on npm, PyPI, crates.io or Maven Central yet, and the install lines here will get shorter when they are.
| Library | Source |
|---|---|
| TypeScript, Effect, React, Next.js, Vue | snekot-js |
| Python | snekot-python |
| Rust | snekot-rust |
| Swift | snekot-swift |
| Kotlin | snekot-kotlin |
| The browser script | snekot-browser |
Use a private key (sk_…) on a server and a public key (pk_…) in anything that ships to other people, such as a web page or a phone app. See Keys. Every library sends to https://api.snekot.co unless you give it another endpoint.
Every SDK behaves the same way:
- One attempt may take 10 seconds.
- A network failure or a server error is retried once, after a quarter of a second.
- A refusal, such as a bad channel name or a spent allowance, is never retried. It surfaces with the server’s own sentence for what to fix.
- Tracking can be switched off, so tests and local runs send nothing.
- Each has
experiment, which answers with a person’s variant of an A/B test.
TypeScript
Runs on Node 18 and later, Deno, Bun and edge runtimes. No dependencies. Works with import and with require.
npm install https://github.com/snekot-co/snekot-js/releases/download/0.2.0/snekot-sdk-0.2.0.tgz
That installs the package as @snekot/sdk, and works the same with pnpm, yarn and bun.
import { Client } from '@snekot/sdk';
const events = new Client({ token: process.env.SNEKOT_TOKEN, project: 'acme-store' });
await events.track({ channel: 'payments', event: 'New subscription', notify: true });
await events.identify({ user_id: 'user-123', properties: { plan: 'pro' } });
await events.group({ group_id: 'acme', user_id: 'user-123', properties: { name: 'Acme' } });
await events.subscribe({ email: '[email protected]', name: 'Jane Park' });
await events.insight.track({ title: 'MRR', value: '$1,289' });
await events.insight.increment({ title: 'Orders', value: 1 });
A refusal throws HTTPResponseError, with the status and the server’s sentence as its message. disableTracking: true makes every call succeed without sending anything.
Effect
A service with layers, and failures as typed values. It is in the same package as the TypeScript client, and needs effect 3.19 or later.
import { Effect } from 'effect';
import { Events } from '@snekot/sdk/effect';
const program = Effect.gen(function* () {
const events = yield* Events;
yield* events.track({ channel: 'payments', event: 'New subscription', notify: true });
yield* events.subscribe({ email: '[email protected]' });
}).pipe(Effect.catchTag('PublishRefused', (refusal) => Effect.logWarning(refusal.message)));
program.pipe(Effect.provide(Events.layerConfig), Effect.runPromise);
Events.layerConfig reads SNEKOT_TOKEN, SNEKOT_PROJECT and, optionally, SNEKOT_ENDPOINT. The token is redacted, so it never prints in a log or a trace. Events.layer(options) takes the values directly, and Events.layerDisabled sends nothing.
A call fails with PublishRefused, when the server said no, or PublishFailed, when there was no usable answer after one retry. events.experiment(…) answers with a person’s variant of an A/B test.
Rust
Async, on reqwest. It needs a Tokio runtime.
cargo add snekot-events --git https://github.com/snekot-co/snekot-rust --tag 0.3.0
use snekot_events::{Client, Subscribe, Track};
let events = Client::builder(token, "acme-store").build();
events
.track(Track::new("payments", "New subscription").icon("💰").notify(true).tag("plan", "pro"))
.await?;
events.insight_increment("Orders", 1, None).await?;
events.subscribe(Subscribe::new("[email protected]").name("Jane Park")).await?;
Errors are Error::Refused { status, message }, Error::Server { status } and Error::Unreachable.
For a program that is not async, add --features blocking to the install line and use snekot_events::blocking::Client, whose calls wait for the answer.
Swift
A Swift package for iOS 15, macOS 12, tvOS 15, watchOS 8 and later, with no dependencies. In Xcode, choose File, Add Package Dependencies and paste https://github.com/snekot-co/snekot-swift. In a Package.swift:
.package(url: "https://github.com/snekot-co/snekot-swift", from: "0.3.0")
import SnekotEvents
let events = SnekotEvents(token: token, project: "acme-store")
try await events.track(channel: "payments", event: "New subscription", icon: "💰", notify: true, tags: ["plan": "pro"])
try await events.incrementInsight("Orders")
try await events.subscribe("[email protected]", name: "Jane Park")
A refusal throws SnekotError.refused(status:message:). An app is on other people’s devices, so give it a public key.
A phone is not always online. Pass queue: OfflineQueue() and a call that gets no answer is kept on the device and sent later, instead of thrown. See Offline.
Kotlin
For the JVM, Java 11 and later, with no dependencies. It is two files: until it is on Maven Central, copy SnekotEvents.kt and OfflineQueue.kt into your project. Calls block, so run them off the main thread.
import co.snekot.events.SnekotEvents
val events = SnekotEvents(token = token, project = "acme-store")
events.track(channel = "payments", event = "New subscription", icon = "💰", notify = true, tags = mapOf("plan" to "pro"))
events.insight.increment("Orders")
events.subscribe("[email protected]", name = "Jane Park")
A refusal throws RefusedException; no answer after one retry throws UnreachableException.
On Android, pass your own Transport: the default uses the JDK’s HTTP client, which Android does not ship. The repository’s README has one over OkHttp.
Offline
The Swift and Kotlin libraries can keep what they could not send. In Kotlin, pass queue = OfflineQueue(context.filesDir); in Swift, queue: OfflineQueue().
- A call that gets no answer is kept on the device instead of thrown. What was kept goes out, oldest first, before the next call that gets through, or when you call
flush(). - At most 500 events are kept, for at most 7 days. Both can be changed, and
clear()forgets them, for when someone signs out. - A refusal is still thrown and never kept. If the server says there are too many requests for now, what is waiting stays for the next try.
- Only the bodies are written to the device, in the app’s own storage. The key is not.
- A kept event keeps the moment it happened. Like any event sent with a time, it is not announced on the live feed, sends no push notification and is not forwarded.
- A public key can place an event up to 7 days back, which is the queue’s default age limit. With a public key, keep the limit at 7 days or less: an older event is refused and dropped.
Python
One module, standard library only, for Python 3.8 and later.
pip install "snekot-events @ git+https://github.com/snekot-co/[email protected]"
from snekot_events import Client
events = Client(token=token, project="acme-store")
events.track(channel="payments", event="New subscription", icon="💰", notify=True, tags={"plan": "pro"})
events.insight.increment(title="Orders", value=1)
events.subscribe("[email protected]", name="Jane Park")
A refusal raises Refused, with the server’s sentence, its status and the answer as data. No answer after one retry raises Unreachable. Both are a FailedToPublish.
React, Next.js and Vue
These are in the TypeScript package, and wrap the browser script. React and Next.js get an EventsProvider and a useEvents() hook with track, identify, group, subscribe, experiment, setUserId, clearUserId and setDebug; Vue gets a plugin and the same functions. Use a public key with them.
import { EventsProvider, useEvents } from '@snekot/sdk/react';
<EventsProvider token="YOUR_PUBLIC_KEY" project="acme-store">{children}</EventsProvider>
The provider also takes the script’s options, remember, outbound, downloads and channel, which the script’s page describes. The module is marked 'use client', so in Next’s App Router the provider can go straight into a server layout. useExperiment(name, variants) gives the visitor’s variant of an A/B test, or null until it is known.
import Events, { track } from '@snekot/sdk/vue';
app.use(Events, { token: 'YOUR_PUBLIC_KEY', project: 'acme-store' });
subscribe(email, properties) puts an address on the project’s newsletter list from a signup field of your own, and answers true once it is in:
const { subscribe } = useEvents();
const ok = await subscribe(email); Next Web pages