users - Vibefollow

The vf.users resource handles user upsert and lifecycle event emission. It wraps POST /api/v1/users (for identify), POST /api/v1/users/bulk (for identifyBulk), and POST /api/v1/events (for every lifecycle helper).

`identify(userId, traits)`

Upserts a user. Same call works for first-touch and updates — the backend deduplicates by external_user_id.

await vf.users.identify('usr_42', {
  email: 'jane@acme.io',
  name: 'Jane Doe',
  plan: 'pro',
  signupDate: '2026-05-17T14:00:00Z',
  company: 'Acme Inc.',
  role: 'engineering_lead',
});

userId

string

required

Your primary key for the user. Used as external_user_id server-side. Stable across re-identifies.

traits

IdentifyTraits

required

Trait bag. The known fields email, name, plan, signupDate, company, role are stored in dedicated columns; everything else flows into the traits JSON column.

Show IdentifyTraits shape

interface IdentifyTraits {
  email?: string;
  name?: string;
  plan?: string;
  signupDate?: string;
  company?: string;
  role?: string;
  [k: string]: unknown;
}

Returns: Promise<void>. Throws on validation / network / auth failure — see Errors.

`identifyBulk(records)`

Upserts up to 1,000 users in a single POST. The backfill counterpart to identify() — pair with chunk() for larger imports.

const result = await vf.users.identifyBulk([
  { external_user_id: 'usr_42', email: 'jane@acme.io', traits: { plan: 'pro' } },
  { external_user_id: 'usr_43', email: 'noel@acme.io', traits: { plan: 'trial' } },
]);

console.log(result.data.accepted); // 2
console.log(result.data.errors); // []

records

BulkUserRecord[]

required

Array of user records. Empty arrays short-circuit (no network call); arrays larger than 1,000 throw RangeError.

Show BulkUserRecord shape

interface BulkUserRecord {
  external_user_id: string;   // required
  email?: string;
  timezone?: string;
  traits?: IdentifyTraits;
}

Returns: Promise<BulkIngestResponse>. Records are validated and queued independently — a single bad row doesn’t sink the batch.

Show BulkIngestResponse shape

interface BulkIngestResponse {
  data: {
    accepted: number;            // records queued
    rejected: number;            // records that failed validation
    errors: BulkIngestError[];   // per-index validation failures
  };
  meta: { received: number };    // total records in the request
}

interface BulkIngestError {
  index: number;     // position in the input array
  code: string;      // e.g. "validation"
  message: string;
  field?: string;    // e.g. "email"
}

Idempotency comes for free from the (project_id, external_user_id) uniqueness constraint on tracked_users. A chunk that returns 429 or 5xx is safe to retry — duplicate external_user_ids become updates, not new rows.

Backfilling more than 1,000 users

Pair with the exported chunk() helper:

import { VibeFollow, chunk } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

for (const slice of chunk(allUsers, 1000)) {
  const result = await vf.users.identifyBulk(slice);
  if (result.data.errors.length > 0) {
    console.warn('skipped', result.data.errors);
  }
}

chunk() is a generator — the source array isn’t materialised twice in memory, which matters for very large backfills.

When the queue is saturated

If the project’s ingest queue has more than 50,000 jobs waiting, identifyBulk() throws RateLimitError with the standard Retry-After semantics. Catch and back off:

import { RateLimitError } from '@vibefollow/sdk';

for (const slice of chunk(allUsers, 1000)) {
  try {
    await vf.users.identifyBulk(slice);
  } catch (err) {
    if (err instanceof RateLimitError) {
      await new Promise((r) => setTimeout(r, err.retryAfterMs ?? 5_000));
      await vf.users.identifyBulk(slice); // safe — idempotent
      continue;
    }
    throw err;
  }
}

Lifecycle helpers

All ten return Promise<void> and emit the canonical event name from STANDARD_EVENT_NAMES. Properties are optional unless flagged required.

`signedUp(userId, properties?)`

Emits user_signed_up.

await vf.users.signedUp('usr_42', {
  plan: 'trial',
  source: 'organic',
});

userId

string

required

External user ID.

properties.plan

string

Plan the user signed up on (trial, pro, enterprise).

properties.source

string

Marketing source (organic, referral, ads, …).

`trialStarted(userId, properties?)`

Emits trial_started.

await vf.users.trialStarted('usr_42', { trialDays: 14 });

properties.trialDays

number

Integer length of the trial in days. Vibefollow derives the trial-end date from it (occurredAt + trialDays), which drives the trial_expiring trigger automatically — no separate expiry event needed.

`featureUsed(userId, properties)`

Emits feature_used. feature is required.

await vf.users.featureUsed('usr_42', {
  feature: 'dashboard_export',
  count: 1,
});

properties.feature

string

required

Stable feature identifier (snake_case recommended).

properties.count

number

Times used in this interaction. Default 1 server-side.

`onboardingStep(userId, properties)`

Emits onboarding_step. step is required.

await vf.users.onboardingStep('usr_42', {
  step: 'connect_integration',
  completed: true,
});

properties.step

string

required

Onboarding step identifier.

properties.completed

boolean

Whether this step was just completed (true) or merely started (false).

`subscriptionChanged(userId, properties)`

Emits subscription_changed. to is required. interval is denormalised onto the user row for audience filters.

await vf.users.subscriptionChanged('usr_42', {
  from: 'trial',
  to: 'pro',
  interval: 'yearly',
  mrr: 9900,
});

properties.from

string

Previous plan.

properties.to

string

required

New plan.

properties.interval

'monthly' | 'yearly' | 'lifetime'

Billing interval.

properties.mrr

number

Monthly recurring revenue, in cents. 9900 = $99/mo.

`subscriptionCancelled(userId, properties?)`

Emits subscription_cancelled. Flips the user to the cancelled lifecycle stage (active-but-departing). Distinct from churned (truly gone after grace period).

await vf.users.subscriptionCancelled('usr_42', {
  reason: 'too_expensive',
  effectiveAt: '2026-06-01T00:00:00Z',
});

properties.reason

string

Free-text cancellation reason.

properties.effectiveAt

string

ISO 8601 timestamp at which access actually ends. Defaults to “now” server-side if omitted.

`paymentFailed(userId, properties?)`

Emits payment_failed.

await vf.users.paymentFailed('usr_42', { reason: 'card_declined' });

properties.reason

string

Decline reason from your billing system (card_declined, insufficient_funds, …).

`trialExpiring(userId, properties)`

Emits trial_expiring. trialDays is required.

You usually don’t need this. The trial_expiring trigger is derived automatically from the most recent trial_started event’s trialDays — call trialStarted once with { trialDays } and Vibefollow fires the follow-up when the trial is within ~48h of ending. Emit this explicitly only to re-assert a dynamically-changed window.

await vf.users.trialExpiring('usr_42', { trialDays: 3 });

properties.trialDays

number

required

Integer number of days left in the trial.

`userInvited(userId, properties)`

Emits user_invited. invitedEmail is required.

await vf.users.userInvited('usr_42', {
  invitedEmail: 'colleague@acme.io',
});

properties.invitedEmail

string

required

Email address that received the invitation.

`usageThresholdReached(userId, properties)`

Emits usage_threshold_reached. Drives the plan_limit_upsell trigger — fires when a paying user crosses a usage threshold against a metered plan limit (default ~80%).

await vf.users.usageThresholdReached('usr_42', {
  usagePercent: 85,
  meter: 'seats',
  limit: 10,
});

userId

string

required

External user ID.

properties.usagePercent

number

required

Current usage as a percentage of the plan limit (85 = 85%).

properties.meter

string

Optional free-form label so audience rules can target a specific meter (seats, api_calls, …).

properties.limit

number

Absolute cap, if known.

Why typed helpers vs `events.track()`

You can emit the same ten events through vf.events.track('user_signed_up', …). You shouldn’t, because:

Typo protection

signedUp autocompletes; siignedUp is a type error.

Property shapes

Validated by TypeScript at the call site, not just server-side.

Discoverable

vf.users.<dot> lists the canonical set in IDE autocomplete.

For anything outside the canonical 10, fall back to events.track().

​identify(userId, traits)

​identifyBulk(records)

​Backfilling more than 1,000 users

​When the queue is saturated

​Lifecycle helpers

​signedUp(userId, properties?)

​trialStarted(userId, properties?)

​featureUsed(userId, properties)

​onboardingStep(userId, properties)

​subscriptionChanged(userId, properties)

​subscriptionCancelled(userId, properties?)

​paymentFailed(userId, properties?)

​trialExpiring(userId, properties)

​userInvited(userId, properties)

​usageThresholdReached(userId, properties)

​Why typed helpers vs events.track()

Typo protection

Property shapes

Discoverable

`identify(userId, traits)`

`identifyBulk(records)`

Backfilling more than 1,000 users

When the queue is saturated

Lifecycle helpers

`signedUp(userId, properties?)`

`trialStarted(userId, properties?)`

`featureUsed(userId, properties)`

`onboardingStep(userId, properties)`

`subscriptionChanged(userId, properties)`

`subscriptionCancelled(userId, properties?)`

`paymentFailed(userId, properties?)`

`trialExpiring(userId, properties)`

`userInvited(userId, properties)`

`usageThresholdReached(userId, properties)`

Why typed helpers vs `events.track()`