API Reference

SaaSStinger Lite does not currently expose a public external API.

This documentation describes the internal application interfaces used by the Next.js application.

The main server-side communication layers are:

• Server Actions
• Server Services
• Repository Layer

These layers provide controlled access to application functionality.

Application Flow

Requests generally follow this pattern:

Client Component

        ↓

Server Action

        ↓

Service Layer

        ↓

Repository Layer

        ↓

Firestore

Each layer has a specific responsibility.

Authentication Requirements

Most server operations require an authenticated user.

Authentication is handled through:

• Firebase Authentication
• Next.js server-side checks
• Workspace membership validation

A typical request must verify:

1. User is authenticated
2. User belongs to the workspace
3. User has the required role

Example:

Request

    ↓

Authenticated User?

    ↓

Workspace Membership?

    ↓

Permission Check

    ↓

Execute Action

Server Actions

Server actions are located in:

src/actions/

Examples:

actions/

workspace.ts

invites.ts

member.ts

project.ts

profile.ts

audit-logs.ts

Server actions are responsible for:

• Receiving client requests
• Validating input
• Calling services
• Returning results

Action Response Pattern

Server actions generally return structured results.

Example:

{
  success: true,
  data: result
}

Failure example:

{
  success: false,
  error: "Permission denied"
}

Workspace Actions

Location:

src/actions/workspace.ts

Handles workspace operations.

Common operations:

• Create workspace
• Update workspace
• Manage workspace settings

Create Workspace

Example request:

{
  name: "Acme Workspace"
}

Process:

User

 ↓

Create Workspace Action

 ↓

Workspace Service

 ↓

Create Workspace Document

 ↓

Create Owner Membership

Response:

{
  success: true,
  workspaceId: "workspace-id"
}

Invitation Actions

Location:

src/actions/invites.ts

Handles workspace invitations.

Operations include:

• Create invitation
• Accept invitation
• Revoke invitation

Create Invitation

Request:

{
  workspaceId: "workspace-id",

  email: "user@example.com",

  role: "MEMBER"
}

Validation:

• User permission
• Workspace access
• Valid role

Response:

{
  success: true,
  inviteId: "invite-id"
}

Member Actions

Location:

src/actions/member.ts

Handles membership operations.

Examples:

• Update role
• Remove member
• View members

Project Actions

Location:

src/actions/project.ts

Handles project functionality.

Examples:

• Create project
• Update project
• Delete project

Project operations must verify:

User

 ↓

Workspace Membership

 ↓

Project Ownership

Profile Actions

Location:

src/actions/profile.ts

Handles user profile operations.

Examples:

• Update display name
• Update profile information

Audit Actions

Location:

src/actions/audit-logs.ts

Handles audit-related operations.

Audit logs support:

• Administrative visibility
• Activity tracking
• Compliance history

Audit access is limited to:

• OWNER
• ADMIN

Service Layer

Services are located in:

src/services/

Services contain business logic.

Examples:

services/

workspace/

invite/

team/

profile/

auth/

Example Service Responsibility

A workspace service may handle:

Create Workspace

1. Validate request

2. Create workspace

3. Create membership

4. Create usage record

5. Create audit event

Repository Layer

Repositories are located in:

src/server/repositories/

Repositories handle Firestore communication.

Examples:

workspace.repository.ts

membership.repository.ts

project.repository.ts

Repositories should not contain business rules.

Authentication Context

Server-side operations may require:

• User ID
• Workspace ID
• Membership role

Example:

{
  userId: "uid",

  workspaceId: "workspace-id",

  role: "OWNER"
}

Permission Checks

Permissions are controlled through:

• Membership records
• RBAC utilities
• Firestore rules

Example:

OWNER

Allowed:
- Manage workspace
- Manage members
- View audit logs


MEMBER

Allowed:
- Access workspace features

Error Handling

Common errors:

Authentication Error

Example:

User not authenticated

Authorization Error

Example:

Insufficient permissions

Validation Error

Example:

Invalid input

Adding a New Server Operation

Recommended process:

1. Create server action
2. Validate input
3. Add service logic
4. Add repository methods
5. Update types
6. Add permissions
7. Test with emulator

Security Guidelines

Never:

• Trust client permissions
• Directly expose Firestore writes
• Return sensitive server data
• Expose Firebase Admin credentials

Always:

• Verify authentication
• Verify workspace membership
• Check permissions server-side

Related Articles

• Creating Server Actions
• Working With Services
• Repository Pattern
• RBAC Permissions
• Firestore Schema

Next Steps

Continue with Changelog Reference to document SaaSStinger Lite versions and changes.