Skip to content

SDK surface reference

This document outlines the public PHP surface. Classes provide the PHP mapping for the OpenAPI endpoint contract.

Entry points

OkatanaClient

Construct OkatanaClient with a Configuration object, or use OkatanaClient::create().

$client = OkatanaClient::create(
    baseUrl: 'https://pm.example.com',
    apiKey: $_ENV['OKATANA_TOKEN'],
);

Public service accessors:

Method Service
organizations() OrganizationsApi
projects() ProjectsApi
boards() BoardsApi
tickets() TicketsApi
documents() DocumentsApi
notifications() NotificationsApi
request() low-level relative /api/v1 request

Configuration

Constructor arguments:

Argument Type Default Meaning
baseUrl string required Deployment origin or complete /api/v1 base URL.
apiKey string required Okatana bearer credential.
timeout float 30.0 Default Guzzle request timeout in seconds.
userAgent string SDK identifier Outbound User-Agent value.
retryPolicy ?RetryPolicy safe-read policy Retry policy for transport errors and selected statuses.

The base URL must be absolute HTTP(S), cannot contain a query or fragment, and has no package default.

Service methods

OrganizationsApi

  • get(string $organization): ApiResponse

ProjectsApi

  • list(string $organization): ApiResponse
  • create(string $organization, CreateProjectRequest|array $request): ApiResponse
  • get(string $project): ApiResponse
  • update(string $project, UpdateProjectRequest|array $request): ApiResponse
  • delete(string $project): ApiResponse
  • members(string $project): ApiResponse
  • labels(string $project): ApiResponse
  • tags(string $project): ApiResponse
  • analytics(string $project): ApiResponse

BoardsApi

  • list(string $project): ApiResponse
  • create(string $project, CreateBoardRequest|array $request): ApiResponse
  • update(string $board, UpdateBoardRequest|array $request): ApiResponse
  • reorder(string $project, ReorderBoardsRequest|array $request): ApiResponse
  • delete(string $board, ?string $moveToBoardId = null): ApiResponse

TicketsApi

  • list(string $project, ?TicketListOptions $options = null): ApiResponse
  • create(string $project, CreateTicketRequest|array $request): ApiResponse
  • reorder(string $project, ReorderTicketsRequest|array $request): ApiResponse
  • get(string $ticket): ApiResponse
  • update(string $ticket, UpdateTicketRequest|array $request): ApiResponse
  • delete(string $ticket): ApiResponse
  • move(string $ticket, MoveTicketRequest|array $request): ApiResponse
  • comment(string $ticket, TicketCommentRequest|array $request): ApiResponse

DocumentsApi

  • list(string $organization, ?DocumentListOptions $options = null): ApiResponse
  • create(string $organization, CreateDocumentRequest|array $request): ApiResponse
  • get(string $document): ApiResponse
  • update(string $document, UpdateDocumentRequest|array $request): ApiResponse
  • delete(string $document): ApiResponse
  • comment(string $document, DocumentCommentRequest|array $request): ApiResponse

NotificationsApi

  • send(string $organization, SendNotificationRequest|array $request): ApiResponse

Request classes

Create and command payloads are immutable readonly value objects:

  • CreateProjectRequest
  • CreateBoardRequest
  • ReorderBoardsRequest
  • CreateTicketRequest
  • ReorderTicketsRequest
  • MoveTicketRequest
  • TicketCommentRequest
  • CreateDocumentRequest
  • DocumentCommentRequest
  • SendNotificationRequest

List option objects:

  • TicketListOptions
  • DocumentListOptions

PATCH builders preserve the distinction between an omitted field and explicit JSON null:

  • UpdateProjectRequest
  • UpdateBoardRequest
  • UpdateTicketRequest
  • UpdateDocumentRequest

Every service write method also accepts an associative array as a forward-compatibility escape hatch.

Enums

  • TicketPriority: lowest, low, normal, high, highest, critical.
  • DocumentStatus: draft, published.
  • Scope: all current external API scopes, including *.

Response objects

ApiResponse

Important members and methods:

  • statusCode — raw HTTP status.
  • headers — normalized response headers.
  • body — unmodified response body string.
  • json — decoded JSON object/array or null for an empty body.
  • data() — unwrap the top-level data envelope when present.
  • collection() — return a simple collection or paginator item collection.
  • pagination() — return Pagination metadata when the response uses the documented Laravel paginator shape.
  • header(string $name) — first joined header value.
  • requestId() — common request/correlation ID header lookup.
  • isNoContent() — true for HTTP 204.

Pagination

Provides currentPage, lastPage, perPage, total, nextPageUrl, previousPageUrl, and items while retaining the raw paginator object.

Models

Models are optional typed views. They keep the source object in raw so unknown response fields remain available.

  • Project
  • Board
  • Ticket
  • Document
  • DocumentTag
  • ApiError

Use response helpers directly for endpoint payloads that do not have a schema in the supplied OpenAPI document. The SDK does not invent fields for underspecified responses.

Exceptions

All SDK exceptions derive from OkatanaException.

Exception Condition
ConfigurationException invalid base URL, empty token, invalid timeout, or invalid configuration
TransportException PSR-18 transport could not send/parse a request after allowed retry attempts
AuthenticationException HTTP 401
AuthorizationException HTTP 403
NotFoundException HTTP 404
ValidationException HTTP 422; exposes Laravel-style errors()
RateLimitException HTTP 429; exposes parsed Retry-After seconds when available
ApiException other HTTP error status
UnexpectedResponseException malformed or unexpected success payload

Transport extension points

OkatanaClient accepts:

  • Psr\Http\Client\ClientInterface;
  • Psr\Http\Message\RequestFactoryInterface;
  • Psr\Http\Message\StreamFactoryInterface;
  • Psr\Log\LoggerInterface;
  • SDK Sleeper for deterministic retry tests.

The default implementation uses Guzzle, but package consumers can inject a different PSR-18 client.