@neuphlo/api

TypeScript client SDK for the Neuphlo API. This package provides a type-safe, contract-first API client for interacting with the Neuphlo platform.

Installation

npm install @neuphlo/api
# or
pnpm add @neuphlo/api
# or
yarn add @neuphlo/api

Quick Start

import { createApiClient } from '@neuphlo/api';

// Initialize the client
const api = createApiClient({
  baseUrl: 'https://api.neuphlo.com', // or your backend URL
  credentials: 'include', // for cookie-based auth
});

// Use the API
const user = await api.users.getCurrentUser();
console.log('Current user:', user);

// List workspaces
const workspaces = await api.workspaces.list();
console.log('Workspaces:', workspaces);

Authentication

The API client supports cookie-based authentication via Better Auth. Make sure to set credentials: 'include' when initializing the client.

const api = createApiClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
});

Available Endpoints

✅ Implemented (v0.1.0)

• Auth - Authentication and session management (via Better Auth)
  • Sign in, sign out, session verification
• Users - User profile management
  • getCurrentUser(), updateCurrentUser(data)

🚧 Planned

v0.2.0 - Core Platform

• Workspaces - Workspace management
  • list(), get(id), getCurrent(), create(data), update(id, data), delete(id), switchTo(id), invite(workspaceId, data)
• Workspace Users - Member management
  • list(params), get(id), add(workspaceId, data), remove(workspaceId, userId), updateRole(workspaceId, userId, data), acceptInvite(invitationId)
• Permissions - Permission management
  • list(params), check(data), grant(data), revoke(id), listByUser(userId), listByWorkspace(workspaceId)

v0.3.0 - Task Management

• Projects - Project organization
  • list(params), get(id), create(data), update(id, data), delete(id), archive(id), unarchive(id)
• Node Types - Task/request type configuration
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), reorder(workspaceId, orderedIds)
• Node States - Workflow state management
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), reorder(workspaceId, orderedIds)
• Nodes - Tasks and requests
  • list(params), get(id), create(data), update(id, data), delete(id), transition(id, data), assign(id, userId), unassign(id), addComment(id, content)

v0.4.0 - Knowledge Base

• Articles - Knowledge base articles
  • list(workspaceId, folderId?), get(id), create(data), update(id, data), delete(id), search(params), publish(id), unpublish(id)
• Folders - Folder organization
  • list(workspaceId, parentId?), get(id), create(data), update(id, data), delete(id), move(id, data), listChildren(id)
• Help Centers - Public documentation sites
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), listCollections(id), listArticles(id)

v0.5.0 - Teams & Collaboration

• Teams - Team management
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), addMember(teamId, data), removeMember(teamId, userId)
• Messages - Comments and discussions
  • list(params), get(id), create(data), update(id, data), delete(id), listByEntity(entityType, entityId, workspaceId)
• Activities - Activity logs
  • list(params), listByEntity(entityType, entityId, workspaceId), listByUser(userId, workspaceId)

v0.6.0 - Companies & Contacts

• Companies - Company management
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), search(params)
• Contacts - Contact management
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), listByCompany(companyId)
• Portals - Customer portals
  • list(workspaceId), get(id), create(data), update(id, data), delete(id), addUser(portalId, data), removeUser(portalId, userId), getPublic(slug)

v0.7.0 - Testing Framework

• Testing - Comprehensive test management
  • Test Projects: listProjects(), getProject(id), createProject(data), updateProject(id, data), deleteProject(id)
  • Test Designs: listDesigns(), getDesign(id), createDesign(data), updateDesign(id, data), deleteDesign(id)
  • Test Cases: listCases(), getCase(id), createCase(data), updateCase(id, data), deleteCase(id)
  • Test Suites: listSuites(), getSuite(id), createSuite(data), updateSuite(id, data), deleteSuite(id), addToSuite(), removeFromSuite()
  • Test Runs: listRuns(), getRun(id), createRun(data), updateRun(id, data), executeRun(id, results)
  • Results: getResults(testRunId), getResultHistory(testCaseId)

v0.8.0+ - Advanced Features

• Integrations - Third-party integrations
  • list(workspaceId, provider?), get(id), create(data), update(id, data), delete(id), connect(id, data), disconnect(id), sync(id)
• Reports - Custom dashboards and reports
  • list(workspaceId, type?), get(id), create(data), update(id, data), delete(id), execute(id, data?), getSnapshot(reportId, snapshotDate)
  • Widgets: addWidget(data), updateWidget(id, data), deleteWidget(id)
• Feature Flags - Feature management
  • list(workspaceId), get(id), create(data), update(id, enabled), delete(id), check(data), enable(workspaceId, feature), disable(workspaceId, feature)

TypeScript Support

This package is built with TypeScript and provides full type safety. All types are automatically inferred from the Drizzle database schema.

import type { User, Workspace, Node, TestCase } from '@neuphlo/api';

// All API responses are fully typed
const user: User = await api.users.getCurrentUser();
const workspaces: Workspace[] = await api.workspaces.list();

Configuration Options

const api = createApiClient({
  // Base URL of the API (required)
  baseUrl: string;

  // Credentials mode for cookies (default: 'include')
  credentials?: RequestCredentials;

  // Additional headers to include in all requests
  headers?: Record<string, string>;

  // Custom fetch implementation (default: global fetch)
  fetch?: typeof fetch;
});

Error Handling

The client throws errors for non-2xx responses. Always wrap API calls in try-catch blocks:

try {
  const workspace = await api.workspaces.get(workspaceId);
  console.log('Workspace:', workspace);
} catch (error) {
  console.error('Failed to fetch workspace:', error);
}

Development Status

This package uses a contract-first approach. All API methods are defined upfront with proper TypeScript types, even though backend endpoints may not be implemented yet.

• Methods marked as IMPLEMENTED are fully functional
• Methods marked as NOT_IMPLEMENTED will return appropriate errors until backend support is added
• Check the @status JSDoc comment on each method to see its implementation status

Private Package

This is a private npm package restricted to authorized users only. It is not published to the public npm registry.

License

See LICENSE for details.

Contributing

This package is part of the Neuphlo monorepo. See the main repository README for contribution guidelines.

Support

For issues and questions, please file an issue in the main repository.