TypeScript SDK

npm install @phosra/sdk

{ "dependencies": { "@phosra/sdk": "0.1.0" } }

const phosra = new PhosraClient({
  apiKey: process.env.PHOSRA_API_KEY, // phosra_live_… — no baseUrl → https://prodapi.phosra.com/api/v1
});

// API key (server-to-server)
const phosra = new PhosraClient({
  apiKey: process.env.PHOSRA_API_KEY, // phosra_test_… or phosra_live_…
});

// Bearer token (user sessions)
const phosra = new PhosraClient({
  accessToken: 'eyJhbGciOi...',
});

// Device key — either via config or the static helper:
const device = new PhosraClient({ deviceKey: 'phosra_dev_...' });
const device2 = PhosraClient.forDevice({ deviceKey: 'phosra_dev_...' });

const phosra = new PhosraClient({
  accessToken: currentAccessToken,
  onTokenExpired: async () => {
    const { access_token } = await refreshMySession(); // your refresh logic
    return access_token; // the request is retried with this token
  },
});

// After a manual login/refresh you can also set it directly:
phosra.setAccessToken(newAccessToken);

// Auth
phosra.auth.register({ email, password, name })   // 404 — no such route; use WorkOS AuthKit
phosra.auth.login({ email, password })            // 404 — no such route; use WorkOS AuthKit
phosra.auth.refresh(refreshToken)                 // 404 — no such route; use onTokenExpired
phosra.auth.logout()
phosra.auth.me()

// Families
phosra.families.list()
phosra.families.create({ name })
phosra.families.get(familyId)
phosra.families.update(familyId, { name })
phosra.families.delete(familyId)

// Children
phosra.children.create(familyId, { name, birth_date })
phosra.children.list(familyId)
phosra.children.get(childId)
phosra.children.update(childId, { name })
phosra.children.delete(childId)
phosra.children.ageRatings(childId)

// Policies
phosra.policies.create(childId, { name })
phosra.policies.list(childId)
phosra.policies.get(policyId)
phosra.policies.update(policyId, { name, priority })
phosra.policies.delete(policyId)
phosra.policies.activate(policyId)
phosra.policies.pause(policyId)
phosra.policies.generateFromAge(policyId)

// Rules
phosra.rules.list(policyId)
phosra.rules.create(policyId, { category, enabled, config })
phosra.rules.update(ruleId, { enabled, config })
phosra.rules.delete(ruleId)
phosra.rules.bulkUpsert(policyId, rules)

// Enforcement
phosra.enforcement.trigger(childId, { platform_ids? })
phosra.enforcement.listJobs(childId)
phosra.enforcement.getJob(jobId)
phosra.enforcement.getResults(jobId)
phosra.enforcement.retry(jobId)

// Compliance
phosra.compliance.create({ family_id, platform_id, credentials })
phosra.compliance.list(familyId)
phosra.compliance.verify(linkId)
phosra.compliance.delete(linkId)

// Webhooks
phosra.webhooks.create({ family_id, url, events })
phosra.webhooks.list(familyId)
phosra.webhooks.get(webhookId)
phosra.webhooks.update(webhookId, { url, events, active })
phosra.webhooks.delete(webhookId)
phosra.webhooks.test(webhookId)
phosra.webhooks.deliveries(webhookId)

// Platforms
phosra.platforms.list()
phosra.platforms.get(platformId)
phosra.platforms.byCategory(category)
phosra.platforms.byCapability(capability)

// Setup
phosra.setup.quick({ child_name, birth_date, strictness? })

import {
  PhosraClient,
  PhosraApiError,
  PhosraNotFoundError,
} from '@phosra/sdk';

try {
  // A well-formed UUID that does not exist → 404 (PhosraNotFoundError).
  // A malformed id (e.g. 'nonexistent-id') returns 400 (invalid UUID) and
  // surfaces as the base PhosraApiError, not PhosraNotFoundError.
  const family = await phosra.families.get('00000000-0000-4000-8000-000000000000');
} catch (err) {
  if (err instanceof PhosraNotFoundError) {
    // 404 — dedicated subclass
    console.log('not found');
  } else if (err instanceof PhosraApiError) {
    console.log(err.statusCode);  // e.g. 404, 422, 429
    console.log(err.code);        // machine-readable code, if the API sent one
    console.log(err.details);     // extra fields from the response body
    console.log(err.message);
  }
}

import { PhosraRateLimitError } from '@phosra/sdk';

try {
  await phosra.families.list();
} catch (err) {
  if (err instanceof PhosraRateLimitError) {
    await new Promise(r => setTimeout(r, (err.retryAfter ?? 1) * 1000));
    // ...then retry
  }
}

import { PhosraClient } from '@phosra/sdk';

const phosra = new PhosraClient({
  apiKey: process.env.PHOSRA_API_KEY!,
});

async function main() {
  // 1. Quick setup
  const setup = await phosra.setup.quick({
    child_name: 'Emma',
    birth_date: '2016-03-15',
    strictness: 'recommended',
  });

  console.log(`Created ${setup.age_group} policy with ${setup.rule_summary.total_rules_enabled} rules`);

  // 2. Connect a platform
  const link = await phosra.compliance.create({
    family_id: setup.family.id,
    platform_id: 'nextdns',
    credentials: process.env.NEXTDNS_API_KEY!,
  });

  console.log(`Connected NextDNS: ${link.status}`);

  // 3. Trigger enforcement
  const job = await phosra.enforcement.trigger(setup.child.id);
  console.log(`Enforcement job started: ${job.id}`);

  // 4. Poll for results
  let status = job.status;
  while (status === 'pending' || status === 'running') {
    await new Promise(r => setTimeout(r, 2000));
    const updated = await phosra.enforcement.getJob(job.id);
    status = updated.status;
  }

  // 5. Check results
  const results = await phosra.enforcement.getResults(job.id);
  for (const result of results) {
    console.log(`${result.platform_id}: ${result.rules_applied} applied, ${result.rules_failed} failed`);
  }
}

main();

import { PhosraClient } from '@phosra/sdk';

const phosra = new PhosraClient({
  baseUrl: 'https://phosra-api-sandbox-production.up.railway.app/api/v1',
});

const r = await phosra.setup.quick({
  child_name: 'Emma',
  birth_date: '2016-03-15',
  strictness: 'recommended',
});
console.log(r.family.name, r.age_group, r.rule_summary.total_rules_enabled);

const rules = await phosra.rules.list(r.policy.id);
console.log('rules:', rules.length);

Emma's Family preteen 20
rules: 20