JavaScript / TypeScript SDK

import { createClient } from "@nebutra/sdk";

const nebutra = createClient({
  apiKey: process.env.NEBUTRA_API_KEY!,
  orgId: process.env.NEBUTRA_ORG_ID!,
  // Optional
  baseUrl: "https://api.nebutra.com",  // override for self-hosted
  timeout: 30000,                       // ms, default 30000
  retry: {
    maxAttempts: 3,
    backoff: "exponential",
  },
});

import { verifyToken } from "@nebutra/sdk/server";

const payload = await verifyToken(bearerToken, {
  apiKey: process.env.NEBUTRA_API_KEY!,
});
// { userId, orgId, scopes, plan }

const key = await nebutra.apiKeys.create({
  name: "CI/CD Pipeline",
  scopes: ["project:read"],
  expiresAt: new Date("2027-01-01"),
});
// key.secret is shown ONCE

// Get current org
const org = await nebutra.orgs.get(orgId);

// Update org
await nebutra.orgs.update(orgId, { name: "New Name" });

// List members
const members = await nebutra.members.list({ orgId });

// Invite a member
await nebutra.members.invite({
  orgId,
  email: "[email protected]",
  role: "MEMBER",
});

// Remove a member
await nebutra.members.remove({ orgId, userId });

// List projects (scoped to org automatically)
const { data, meta } = await nebutra.projects.list({
  limit: 20,
  cursor: meta.next_cursor,
});

// Get a project
const project = await nebutra.projects.get("proj_123");

// Create a project
const project = await nebutra.projects.create({
  name: "My Project",
  description: "Optional description",
});

// Update a project
await nebutra.projects.update("proj_123", { name: "New Name" });

// Delete a project
await nebutra.projects.delete("proj_123");

import { can, requirePermission } from "@nebutra/sdk/permissions";

// Check a permission
const allowed = await can(userId, "project:delete", { orgId });

// Throw 403 if not allowed
await requirePermission("project:delete");

// Get quota usage
const quota = await nebutra.metering.getQuota("api_calls");
// { limit, used, remaining, percentage, reset_at }

// Ingest a usage event
await nebutra.metering.ingest({
  metricId: "api_calls",
  tenantId: orgId,
  quantity: 1,
});

// Create a webhook endpoint
const endpoint = await nebutra.webhooks.createEndpoint({
  url: "https://your-app.com/webhooks",
  events: ["project.created", "invoice.paid"],
});

// List endpoints
const endpoints = await nebutra.webhooks.listEndpoints();

// Delete an endpoint
await nebutra.webhooks.deleteEndpoint("wh_123");

// Send a custom event
await nebutra.webhooks.sendEvent({
  id: crypto.randomUUID(),
  eventType: "custom.event",
  payload: { ... },
  tenantId: orgId,
});

import {
  NebutraError,
  NotFoundError,
  ValidationError,
  ForbiddenError,
  RateLimitError,
} from "@nebutra/sdk";

try {
  await nebutra.projects.get("proj_123");
} catch (error) {
  if (error instanceof NotFoundError) {
    // 404 — resource not found
  } else if (error instanceof ForbiddenError) {
    // 403 — insufficient permissions
  } else if (error instanceof ValidationError) {
    console.error(error.fields); // Field-level errors
  } else if (error instanceof RateLimitError) {
    // Wait error.retryAfter seconds
    await sleep(error.retryAfter * 1000);
  } else if (error instanceof NebutraError) {
    console.error(error.code, error.requestId);
  }
}

import type {
  Organization,
  Member,
  Project,
  ApiKey,
  Role,
  Plan,
  Scope,
} from "@nebutra/sdk/types";

npm install @nebutra/react

import {
  useNebutraUser,
  useNebutraOrg,
  useNebutraToken,
  Can,
  NebutraProvider,
} from "@nebutra/react";