@navelcloud/api-client

Api Client

This package provides shared API helpers and API-facing composables for Navel Cloud templates using Nuxt framework. Use the package for code whose primary responsibility is calling or shaping data from the backend API.

Installation

npm install @navelcloud/api-client

Usage

Calling the API

The shared $api client is available through Nuxt.

const { $api } = useNuxtApp()

const response = await $api('/appointments/types')

When TENANT_ID is configured, requests include X-Tenant-ID by default.

For a landlord call, disable the tenant header on that call:

const response = await $api('/some-landlord-endpoint', {
  tenant: false,
})

Do not create a separate landlord client just to omit the tenant header.

Authentication permissions

Authentication endpoints such as login, register, logout, and Socialite authentication are landlord calls. Tenant context on /users/me is authorization context only: it determines which tenant roles and permissions are returned for the authenticated user.

useAuth().fetchUser() uses the normal API tenant context by default. To request roles and permissions for a specific tenant without changing the selected tenant, pass its ID explicitly:

const auth = useAuth()

await auth.fetchUser({ tenantId })

This sends X-Tenant-ID for that /users/me request. Use fetchUser({ tenant: false }) only when an intentionally landlord-scoped user response is required.

useAuth() exposes permission helpers based on user.permissions.

user.permissions may be an array of strings or permission objects, or an object map such as:

{
  'users.get': true,
  'users.*': true,
}

Check one permission with hasPermission:

const auth = useAuth()

auth.hasPermission('users.index')

Wildcard permissions are supported. If the user has users.*, checking users.index returns true.

A wildcard may also be used in the check. If the user has users.index, checking users.* returns true.

Use hasPermissions to check whether the user has any permission from a list:

const auth = useAuth()

auth.hasPermissions([
  'test',
  'users.*',
])

This returns true when at least one requested permission matches one of the user's enabled permissions.

Authentication feature flags

User feature flags are available through user.flags as a boolean object map:

{
  database: true,
  reel: true,
  video: true,
  workflow: true,
}

Check one flag with hasFlag:

const auth = useAuth()

auth.hasFlag('video')

Use hasFlags to check whether at least one flag from a list is enabled:

const auth = useAuth()

auth.hasFlags([
  'video',
  'reel',
])

A flag only matches when its value in user.flags is truthy.

API composables

API-facing composables belong in packages/api-client/app/composables.

Examples include authentication, account management, appointments, collections, Socialite, Storefront, and Wallet.

A composable should keep endpoint details and small response-normalization concerns together. It should not contain page rendering logic or large UI state machines.

Pages call composables and pass the resulting data and callbacks into components.