@gitkraken/milestones-tools

Client library for GitKraken user milestones and demographic metadata, served by identity-service.

What it is

This package wraps the v1 milestone and demographic surface of identity-service in a runtime-agnostic client. It does two things:

• Milestones - detects when a user earns a milestone (first commit, first branch, first PR, first AI event) from actions the host already observes, queues each detection durably, and confirms it with identity-service. Detection runs against an embedded copy of the canonical event manifest, so the client and the server agree on the taxonomy without a round-trip.
• Demographics - reads and writes the user's demographic metadata and the enum sets that constrain each field.

The library never performs HTTP itself, never reads a token from ambient state, and never persists anything directly. The host injects all three: a request function (the same { body, status, headers } shape GitKraken's other client SDKs use, e.g. @gitkraken/provider-apis), a token getter, and a storage port.

Install

pnpm add @gitkraken/milestones-tools

Provide the ports

Everything the library needs from the outside world is passed through MilestonesSdkConfig:

import { createMilestonesClient } from '@gitkraken/milestones-tools';

const client = createMilestonesClient({
    baseUrl: 'https://api.gitkraken.dev',
    // Identifies the host surface reporting milestones (e.g. 'gitlens').
    sourceClient: 'gitlens',
    // Injected request function - omit to use a default fetch-based requester.
    // Plug in your own (e.g. GitKraken's contextFreeMakeRequest) to own the network.
    // `headers` is a Web `Headers` instance (case-insensitive lookups). A fetch
    // response already exposes one; wrap a plain object with `new Headers(obj)`.
    request: async ({ method, url, headers, body }) => {
        const response = await myHttp({ method, url, headers, body });
        return { body: response.body, status: response.status, headers: new Headers(response.headers) };
    },
    // Called per request to supply a fresh bearer token.
    getToken: async () => await myAuth.getAccessToken(),
    // Durable key/value store - back it with disk, localStorage, etc.
    storage: {
        get: async (key) => myStore.get(key) ?? null,
        set: async (key, value) => myStore.set(key, value),
        delete: async (key) => myStore.delete(key),
    },
    // Optional - how long loadMilestones() trusts its cache (default 5 min).
    cacheTtlMs: 5 * 60 * 1000,
    // Optional structured logger.
    logger: console,
});

StoragePort is the only stateful dependency. The library uses it to cache milestone state and to persist the pending-action queue, so detections survive process restarts and are delivered at least once.

Milestones

const { milestones } = client;

// Load the user's achieved milestones (cached for cacheTtlMs).
const state = await milestones.loadMilestones();
console.log(Object.keys(state.achieved));

// Get notified when a queued milestone is confirmed by the server.
const unsubscribe = milestones.onConfirmed((milestoneId) => {
    showCelebration(milestoneId);
});

// Feed actions the host already observes. The client maps each action to a
// milestone via the embedded manifest, skips ones already achieved, enqueues
// the rest, and flushes to identity-service.
await milestones.observe({
    type: 'commit_created',
    at: new Date().toISOString(),
    payload: { surface_name: 'gitlens', kind: 'create' },
});

// Cheap local check against the cached state.
if (await milestones.isAchieved('first_commit')) {
    hideFirstCommitHint();
}

unsubscribe();

A commit_created with kind of cherrypick or revert does not earn first_commit - the embedded manifest's milestone_filter only credits create and amend. Unknown action types are ignored.

Demographics

const { demographic } = client;

const enums = await demographic.getEnums();
const current = await demographic.get();
const updated = await demographic.set({ role: 'softwareEngineer', gitComfortLevel: 'very' });

Canonical manifest

The canonical v1 event taxonomy is embedded in the package and exported as manifest, alongside the eventForMilestone(milestoneId) and eventByName(name) helpers. It is validated with zod at module load, so a malformed manifest fails fast rather than producing silent mis-detections.

import { manifest, eventForMilestone } from '@gitkraken/milestones-tools';

console.log(manifest.events.map((event) => event.event_name));
console.log(eventForMilestone('first_commit')?.event_name); // 'commit_created'

Contributing

This package follows the monorepo's standard tooling - see the root CONTRIBUTING.md. Local commands:

pnpm --filter @gitkraken/milestones-tools build
pnpm --filter @gitkraken/milestones-tools typecheck
pnpm --filter @gitkraken/milestones-tools test

End-to-end tests

pnpm test (and CI) runs unit tests only. The e2e suite hits a live identity-service and is opt-in:

MILESTONES_E2E_TOKEN=<bearer-token> pnpm --filter @gitkraken/milestones-tools test:e2e

Env vars: MILESTONES_E2E_TOKEN (required); MILESTONES_E2E_BASE_URL (optional, defaults to https://devapi.gitkraken.com; gateway that fronts identity-service, no trailing slash, no /v1); MILESTONES_E2E_SOURCE_CLIENT (optional, defaults to gitlens); MILESTONES_E2E_WRITE=1 (optional) to also run the mutating milestone POST. Without the token the suite skips itself.