Internal reference — not the public API

This documents NearSync's internal action-dispatch surface, used by the apps themselves and by tenant automations. It is not the public API and carries no stability guarantee — actions may change or be removed without notice. For the supported, versioned public API see API Reference.

API Gateway Migration

The NearSync API Gateway is a typed, authenticated HTTP layer built on top of the hyper-worker edge function. It provides a single entry point for all platform write operations, replacing direct Supabase client calls with structured API actions routed through a central gateway.

Why the gateway exists

Direct Supabase calls from the frontend work but have limitations for enterprise deployment:

• No centralized audit trail for write operations
• No server-side business logic enforcement
• No rate limiting on write operations
• Tight coupling between UI code and database schema

The gateway solves all four. It also creates an auditable, rate-limited API surface that BYOK clients can integrate against, and decouples the frontend from direct database access - a prerequisite for the future public API and MCP server.

Architecture

All requests flow through the hyper-worker edge function:

Client -> @nearsync/api-client -> POST /functions/v1/hyper-worker -> JWT auth -> rate limiter -> service router -> response

The api-client package handles authentication headers, error parsing, streaming responses, and retry logic.

Dual-path migration pattern

The gateway is deployed using a dual-path pattern: each module's write operations check a feature flag before choosing between direct Supabase access (legacy) and the API gateway (new). This allows incremental migration with instant rollback.

const useGateway = manifest.features?.api_gateway_finance === true;

if (useGateway) {
  await api.call("finance-create-invoice", payload);
} else {
  await supabase.from("finance_invoices").insert(payload);
}

Read operations remain on direct Supabase - the gateway handles writes only. Reads through Supabase use RLS for row-level security, which is already battle-tested.

Feature flags by module

Feature Flag	Module	Endpoints Gated
api_gateway_finance	Finance HQ	14 endpoints: invoice CRUD, expense CRUD + approve/reject, subscription CRUD, approval chains
api_gateway_hrms	People / HRMS	14 endpoints: employee onboard/update, leave submit/approve/reject, payroll process/approve, KPI, SLA, commission
api_gateway_eng	Engineering	9 endpoints: issue create, sprint lifecycle, epic CRUD, meeting CRUD
api_gateway_crm	CRM / Sales	2 endpoints: deal stage move, task create (+ automation triggers)
api_gateway_marketing	Marketing	8 endpoints: campaign/asset/brief/note save and delete
api_gateway_support	Support	4 endpoints: ticket create/move/close/delete
api_gateway_website	Website / CMS	8 endpoints: article/category/page CRUD
api_gateway_ops	Operations	1+ endpoints: procedure create, sentinel operations

All flags default to false (direct Supabase). Set to true in the SystemManifest to enable gateway routing.

Gateway endpoint reference

Finance endpoints (14)

Action	Description
finance-create-invoice	Create a draft invoice. Auto-generates invoice number.
finance-update-invoice	Update invoice fields. Triggers status recalculation.
finance-delete-invoice	Soft-delete an invoice.
finance-create-company-expense	Log a company expense.
finance-create-employee-expense	Submit an employee expense claim.
finance-approve-expense	Approve an expense (requires approver role).
finance-reject-expense	Reject an expense with reason.
finance-mark-expense-paid	Mark expense as paid/reimbursed.
finance-create-subscription	Create a recurring subscription.
finance-update-subscription	Update subscription fields.
finance-cancel-subscription	Cancel a subscription.
finance-approve-expense-approval	Approve in the expense approval chain.
finance-reject-expense-approval	Reject in the expense approval chain.
finance-approve-payroll-approval	Approve a payroll run.

People / HRMS endpoints (14)

Action	Description
hrms-onboard-employee	Onboard a new employee.
hrms-update-employee	Update employee record.
hrms-link-system-user	Link an employee to a system user account.
hrms-submit-leave	Submit a leave request.
hrms-approve-leave	Approve a leave request.
hrms-reject-leave	Reject a leave request.
hrms-create-leave-policy	Create a leave policy.
hrms-process-payroll	Process a payroll run for a period.
hrms-approve-payroll	Approve a processed payroll run.
hrms-process-final-settlement	Calculate final settlement for departing employee.
hrms-submit-kpi-score	Submit a KPI performance score.
hrms-log-sla-metric	Log an SLA compliance metric.
hrms-update-commission	Update commission settings.
hrms-approve-change-request	Approve an employee change request.

Engineering endpoints (9)

Action	Description
eng-create-issue	Create a new issue/ticket.
eng-create-sprint	Create a sprint.
eng-start-sprint	Start a sprint (moves to active).
eng-complete-sprint	Complete a sprint (unfinished issues move to backlog).
eng-reopen-sprint	Reopen a completed sprint.
eng-create-epic	Create an epic.
eng-update-epic	Update epic fields.
eng-delete-epic	Delete an epic.
eng-create-meeting	Create a meeting.

CRM / Sales endpoints (2)

Action	Description
crm-move-deal-stage	Move a deal to a different pipeline stage. Triggers governance rules and automations.
crm-create-task	Create a task linked to a deal.

Marketing endpoints (8)

Action	Description
marketing-save-campaign	Create or update a campaign.
marketing-delete-campaign	Delete a campaign.
marketing-save-asset	Create or update a marketing asset.
marketing-delete-asset	Delete an asset.
marketing-save-brief	Create or update a creative brief.
marketing-delete-brief	Delete a brief.
marketing-save-note	Create or update a note.
marketing-delete-note	Delete a note.

Support endpoints (4)

Action	Description
support-create-ticket	Create a support ticket.
support-move-ticket	Move ticket to a different stage.
support-close-ticket	Close a ticket.
support-delete-ticket	Delete a ticket.

Website / CMS endpoints (8)

Action	Description
website-create-article	Create a KB article.
website-update-article	Update article content.
website-delete-article	Delete an article.
website-create-category	Create a KB category.
website-delete-category	Delete a category.
website-create-page	Create a site page.
website-update-page	Update a page.
website-delete-page	Delete a page.

@nearsync/api-client package

The api-client package provides a typed wrapper for the hyper-worker edge function.

api.call()

Make a request to any hyper-worker endpoint:

import { api } from "@nearsync/api-client";

const result = await api.call<InvoiceResponse>("finance-create-invoice", {
  client_name: "Acme Corp",
  amount: 5000,
  currency: "USD"
});

if (result.error) {
  console.error(result.error.message);
} else {
  console.log(result.data.id);
}

api.stream()

Stream an AI response:

for await (const chunk of api.stream("ai-chat", { prompt: "Summarize Q1" })) {
  process.stdout.write(chunk);
}

api.configure()

Override the default base URL or token provider:

api.configure({
  baseUrl: "https://your-supabase-project.supabase.co/functions/v1/hyper-worker",
  getToken: async () => customJWT
});

BYOK clients: point baseUrl to your own Supabase project URL. The api-client works identically - the only difference is where the edge function runs.

Rollback

Rollback is instant: set the feature flag to false in the SystemManifest. The hook reverts to direct Supabase. No code deployment required.

Action string conventions

• Gateway actions follow the pattern: <module>-<verb>-<entity> (e.g., finance-create-invoice, hrms-approve-leave, eng-start-sprint)
• Legacy actions use shorter names (e.g., create-user, booking, ai-chat) and are not renamed for backward compatibility
• Total registered actions: 86 (56 gateway + 30 legacy)