Streaks

// Via the Amba MCP server (mcp.amba.dev/mcp). Use any MCP-aware agent
// (Claude Code, Cursor, Windsurf) or call the tool directly.
await amba_create_streak({
  project_id: 'prj_…',
  key: 'daily_play', // stable key your app calls qualify with
  name: 'Daily Player',
  period: 'daily', // 'daily' | 'weekly'
  qualifying_event: 'session_started',
  grace_period_hours: 6, // optional — extra time before a miss
  freeze_enabled: true,
  max_freezes: 2,
  freezes_per_n_events: 5, // auto-grant 1 shield every 5 qualifying events
});

import { Amba } from '@layers/amba-web';
 
// On every "user did the thing" event (e.g. finished a daily session)
const streak = await Amba.streaks.qualify('daily_play');
 
// streak.current_count     = 7        ← they're on a 7-day streak
// streak.longest_count     = 12       ← personal best
// streak.status             = 'active'
// streak.freezes_remaining  = 1        ← unused shields in reserve

try {
  await Amba.streaks.qualify('weekly_login');
} catch (e) {
  if (e?.error?.code === 'STREAK_NOT_FOUND') {
    // The streak hasn't been defined for this project yet — call
    // amba_create_streak first. This is a config-time error, never
    // a runtime one; should not reach production.
    console.error('Define this streak using amba_create_streak first.');
  } else {
    throw e;
  }
}

const streaks = await client.streaks.getAll();
// Returns all streak states with definitions

interface Streak {
  id: string;
  /** Stable key — use this with `qualify()`. e.g. `"daily_play"` */
  key: string;
  name: string; // e.g. "Daily Workout"
  current_count: number; // current streak count
  longest_count: number; // all-time best
  last_qualified_at?: string | null; // ISO timestamp of the last qualifying event
  /**
   * Lifecycle state. One of:
   *   "active"  — streak is alive
   *   "broken"  — missed a period; current_count reset to 0
   *   "frozen"  — a shield (freeze) protected the streak from a miss
   */
  status: 'active' | 'broken' | 'frozen';
  /**
   * Unused streak-shield count. Auto-granted by the server every
   * `freezes_per_n_events` qualifying events, capped at `max_freezes` (both
   * configured on the streak). Drops by 1 when a shield is consumed on a miss.
   */
  freezes_remaining: number;
  updated_at: string;
}

// Usually automatic via event tracking, but you can also qualify directly:
await client.streaks.qualify('daily_play');

// This both tracks the event AND qualifies the "Daily Workout" streak
await Amba.events.track('workout_completed', { duration: 30 });

await admin.streaks.create({
  key: 'daily_workout',
  name: 'Daily Workout',
  qualifying_event: 'workout_completed',
  period: 'daily',
  freeze_enabled: true,
  max_freezes: 2,
  freezes_per_n_events: 5,
});

{
  "event_name": "streak_shielded",
  "properties": {
    "streak_id": "us_…",
    "streak_definition_id": "sd_…",
    "freezes_remaining_after": 0
  }
}

POST /v1/admin/projects/:projectId/users/:userId/streaks/:streakDefinitionId/grant-shield
Body: { count?: number }   // default 1

{
  "data": {
    "id": "uuid",
    "current_count": 8,
    "longest_count": 14,
    "last_qualified_at": "2025-01-15T10:30:00Z",
    "status": "active",
    "current_period_start": "2025-01-08"
  }
}

Agent: "Create a daily login streak with a 6-hour grace period"

amba_create_streak({
  project_id: "proj_xxx",
  key: "daily_login",
  name: "Daily Login",
  qualifying_event: "app_open",
  period: "daily",
  grace_period_hours: 6,
  freeze_enabled: true,
  max_freezes: 2
})

import { useEffect, useState } from 'react';
// Bare React Native:
//   import { Amba, type Streak } from '@layers/amba-react-native';
// Expo managed:
import { Amba, type Streak } from '@layers/amba-expo';
 
function StreakCard() {
  const [streaks, setStreaks] = useState<Streak[]>([]);
 
  useEffect(() => {
    Amba.streaks.getAll().then(setStreaks);
  }, []);
 
  const daily = streaks.find((s) => s.key === 'daily_login');
  if (!daily) return null;
 
  const safeCopy = daily.status === 'frozen' ? 'Your streak is safe — a shield kicked in.' : null;
 
  return (
    <View>
      <Text>Current streak: {daily.current_count} days</Text>
      <Text>Longest streak: {daily.longest_count} days</Text>
      <Text>Shields in reserve: {daily.freezes_remaining}</Text>
      {safeCopy ? <Text>{safeCopy}</Text> : null}
    </View>
  );
}