@bosunski/laravel-cloud-sdk 0.1.1

package/README.md

@@ -0,0 +1,56 @@
+# Laravel Cloud SDK (TypeScript)
+
+TypeScript client for the Laravel Cloud API, providing convenient wrappers for applications, environments, deployments, domains, database clusters, and instances endpoints.
+
+## Getting Started
+
+```bash
+pnpm install @bosunski/laravel-cloud-sdk
+```
+
+```ts
+import { LaravelCloudClient } from '@bosunski/laravel-cloud-sdk';
+
+const client = new LaravelCloudClient({ apiToken: process.env.LARAVEL_CLOUD_TOKEN! });
+const apps = await client.applications.list();
+await client.environments.start('env-123', { redeploy: true });
+await client.domains.create('env-123', { name: 'example.com' });
+const databases = await client.databases.list({ include: ['schemas'] });
+await client.instances.create('env-123', {
+	name: 'web-1',
+	type: 'service',
+	size: 'flex.m-1vcpu-1gb',
+	scalingType: 'auto',
+	maxReplicas: 2,
+	minReplicas: 1,
+	usesScheduler: true,
+});
+```
+
+### CDN Usage
+
+The package is published as an ES module, so you can load it via a CDN like jsDelivr:
+
+```html
+<script type="module">
+	import { LaravelCloudClient } from 'https://cdn.jsdelivr.net/npm/@bosunski/laravel-cloud-sdk/+esm';
+
+	const client = new LaravelCloudClient({ apiToken: 'token' });
+	const databases = await client.databases.list();
+	console.log(databases);
+</script>
+```
+
+## Testing
+
+This repository uses [Vitest](https://vitest.dev/) with mocked fetch handlers. Run the full suite with:
+
+```bash
+pnpm test
+```
+
+To inspect coverage output:
+
+```bash
+pnpm test -- --coverage
+```

package/dist/http/client.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { QueryParams } from '../utils/query.js';
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+export interface ClientOptions {
+    apiToken: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    userAgent?: string;
+}
+export interface RequestConfig<TResponse> {
+    path: string;
+    method?: HttpMethod;
+    query?: QueryParams;
+    headers?: Record<string, string>;
+    json?: unknown;
+    formData?: FormData;
+    schema?: z.ZodType<TResponse>;
+    signal?: AbortSignal;
+    accept?: string;
+}
+export declare class HttpClient {
+    private readonly apiToken;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly userAgent?;
+    constructor(options: ClientOptions);
+    request<TResponse = unknown>(config: RequestConfig<TResponse>): Promise<TResponse>;
+}

package/dist/http/client.js

@@ -0,0 +1,79 @@
+import { ApiError } from './errors.js';
+import { buildSearchParams } from '../utils/query.js';
+const DEFAULT_BASE_URL = 'https://cloud.laravel.com/api';
+const defaultFetch = (input, init) => {
+    if (typeof fetch === 'function') {
+        return fetch(input, init);
+    }
+    throw new Error('Global fetch is not available. Provide a fetch implementation in ClientOptions.');
+};
+export class HttpClient {
+    apiToken;
+    baseUrl;
+    fetchImpl;
+    userAgent;
+    constructor(options) {
+        if (!options.apiToken) {
+            throw new Error('apiToken is required to initialize the Laravel Cloud client.');
+        }
+        this.apiToken = options.apiToken;
+        this.baseUrl = options.baseUrl?.replace(/\/$/, '') ?? DEFAULT_BASE_URL;
+        this.fetchImpl = options.fetch ?? defaultFetch;
+        this.userAgent = options.userAgent;
+    }
+    async request(config) {
+        const method = config.method ?? 'GET';
+        const search = buildSearchParams(config.query);
+        const url = `${this.baseUrl}${config.path}${search}`;
+        const headers = new Headers({
+            Authorization: `Bearer ${this.apiToken}`,
+            Accept: config.accept ?? 'application/vnd.api+json',
+            ...config.headers,
+        });
+        if (this.userAgent) {
+            headers.set('User-Agent', this.userAgent);
+        }
+        let body;
+        if (config.formData) {
+            body = config.formData;
+        }
+        else if (config.json !== undefined) {
+            headers.set('Content-Type', 'application/json');
+            body = JSON.stringify(config.json);
+        }
+        const response = await this.fetchImpl(url, {
+            method,
+            headers,
+            body,
+            signal: config.signal,
+        });
+        const contentType = response.headers.get('content-type') ?? '';
+        const isJson = contentType.includes('application/json');
+        let parsedBody;
+        if (response.status !== 204) {
+            if (isJson) {
+                parsedBody = await response.json();
+            }
+            else if (!response.bodyUsed) {
+                parsedBody = await response.text();
+            }
+        }
+        if (!response.ok) {
+            const headersRecord = {};
+            response.headers.forEach((value, key) => {
+                headersRecord[key] = value;
+            });
+            throw new ApiError({
+                status: response.status,
+                statusText: response.statusText,
+                request: { method, url },
+                body: parsedBody,
+                headers: headersRecord,
+            });
+        }
+        if (config.schema) {
+            return config.schema.parse(parsedBody);
+        }
+        return parsedBody;
+    }
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,21 @@
+export interface ApiErrorRequest {
+    method: string;
+    url: string;
+}
+export interface ApiErrorOptions {
+    status: number;
+    statusText: string;
+    request: ApiErrorRequest;
+    body?: unknown;
+    headers?: Record<string, string>;
+    message?: string;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly request: ApiErrorRequest;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+    constructor(options: ApiErrorOptions);
+}
+export declare const isApiError: (error: unknown) => error is ApiError;

package/dist/http/errors.js

@@ -0,0 +1,17 @@
+export class ApiError extends Error {
+    status;
+    statusText;
+    request;
+    body;
+    headers;
+    constructor(options) {
+        super(options.message ?? `Request failed with status ${options.status}`);
+        this.name = 'ApiError';
+        this.status = options.status;
+        this.statusText = options.statusText;
+        this.request = options.request;
+        this.body = options.body;
+        this.headers = options.headers;
+    }
+}
+export const isApiError = (error) => error instanceof ApiError;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { HttpClient, ClientOptions } from './http/client.js';
+import { ApiError, isApiError } from './http/errors.js';
+import { ApplicationsResource, Application, ApplicationListResponse, ApplicationResponse, CreateApplicationPayload, ListApplicationsOptions, Region, UpdateApplicationPayload } from './resources/applications.js';
+import { DeploymentsResource, Deployment, DeploymentListResponse, DeploymentResponse, ListDeploymentsOptions } from './resources/deployments.js';
+import { EnvironmentsResource, Environment, EnvironmentListResponse, EnvironmentResponse, ListEnvironmentsOptions, UpdateEnvironmentPayload, CreateEnvironmentPayload } from './resources/environments.js';
+import { DomainsResource, Domain, DomainListResponse, DomainResponse, ListDomainsOptions, CreateDomainPayload, UpdateDomainPayload } from './resources/domains.js';
+import { DatabasesResource, Database, DatabaseListResponse, DatabaseResponse, ListDatabasesOptions, CreateDatabasePayload, DatabaseTypeDefinition, DatabaseTypeField } from './resources/databases.js';
+import { InstancesResource, Instance, InstanceListResponse, InstanceResponse, ListInstancesOptions, CreateInstancePayload, UpdateInstancePayload, InstanceBackgroundProcess } from './resources/instances.js';
+export declare class LaravelCloudClient {
+    readonly applications: ApplicationsResource;
+    readonly environments: EnvironmentsResource;
+    readonly deployments: DeploymentsResource;
+    readonly domains: DomainsResource;
+    readonly databases: DatabasesResource;
+    readonly instances: InstancesResource;
+    private readonly http;
+    constructor(options: ClientOptions);
+}
+export { HttpClient };
+export type { ClientOptions, Application, ApplicationListResponse, ApplicationResponse, CreateApplicationPayload, ListApplicationsOptions, Region, UpdateApplicationPayload, Deployment, DeploymentListResponse, DeploymentResponse, ListDeploymentsOptions, Environment, EnvironmentListResponse, EnvironmentResponse, ListEnvironmentsOptions, UpdateEnvironmentPayload, CreateEnvironmentPayload, Domain, DomainListResponse, DomainResponse, ListDomainsOptions, CreateDomainPayload, UpdateDomainPayload, Database, DatabaseListResponse, DatabaseResponse, ListDatabasesOptions, CreateDatabasePayload, DatabaseTypeDefinition, DatabaseTypeField, Instance, InstanceListResponse, InstanceResponse, ListInstancesOptions, CreateInstancePayload, UpdateInstancePayload, InstanceBackgroundProcess, };
+export { ApiError, isApiError };

package/dist/index.js

@@ -0,0 +1,28 @@
+import { HttpClient } from './http/client.js';
+import { ApiError, isApiError } from './http/errors.js';
+import { ApplicationsResource, } from './resources/applications.js';
+import { DeploymentsResource, } from './resources/deployments.js';
+import { EnvironmentsResource, } from './resources/environments.js';
+import { DomainsResource, } from './resources/domains.js';
+import { DatabasesResource, } from './resources/databases.js';
+import { InstancesResource, } from './resources/instances.js';
+export class LaravelCloudClient {
+    applications;
+    environments;
+    deployments;
+    domains;
+    databases;
+    instances;
+    http;
+    constructor(options) {
+        this.http = new HttpClient(options);
+        this.applications = new ApplicationsResource(this.http);
+        this.environments = new EnvironmentsResource(this.http);
+        this.deployments = new DeploymentsResource(this.http);
+        this.domains = new DomainsResource(this.http);
+        this.databases = new DatabasesResource(this.http);
+        this.instances = new InstancesResource(this.http);
+    }
+}
+export { HttpClient };
+export { ApiError, isApiError };

package/dist/resources/applications.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { HttpClient } from '../http/client.js';
+import { JsonApiResponse, JsonApiResource } from '../types/jsonApi.js';
+declare const regionSchema: z.ZodEnum<{
+    "us-east-2": "us-east-2";
+    "us-east-1": "us-east-1";
+    "eu-central-1": "eu-central-1";
+    "eu-west-1": "eu-west-1";
+    "eu-west-2": "eu-west-2";
+    "ap-southeast-1": "ap-southeast-1";
+    "ap-southeast-2": "ap-southeast-2";
+    "ca-central-1": "ca-central-1";
+    "me-central-1": "me-central-1";
+}>;
+export type Region = z.infer<typeof regionSchema>;
+export interface ApplicationRepository {
+    fullName?: string;
+    defaultBranch?: string;
+}
+export interface Application {
+    id: string;
+    name: string;
+    slug: string;
+    region: string;
+    slackChannel?: string | null;
+    createdAt: string;
+    repository?: ApplicationRepository;
+    raw: JsonApiResource;
+}
+export interface ListApplicationsOptions {
+    include?: Array<'organization' | 'environments' | 'defaultEnvironment'>;
+    filter?: {
+        name?: string;
+        region?: string;
+        slug?: string;
+    };
+    page?: {
+        number?: number;
+        size?: number;
+    };
+}
+export interface CreateApplicationPayload {
+    repository: string;
+    name: string;
+    region: Region;
+}
+export interface UpdateApplicationPayload {
+    name?: string;
+    slug?: string;
+    defaultEnvironmentId?: string;
+    repository?: string;
+    slackChannel?: string | null;
+}
+export interface ApplicationListResponse extends JsonApiResponse<Application[]> {
+}
+export interface ApplicationResponse extends JsonApiResponse<Application> {
+}
+export declare class ApplicationsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(options?: ListApplicationsOptions): Promise<ApplicationListResponse>;
+    retrieve(applicationId: string, options?: Pick<ListApplicationsOptions, 'include'>): Promise<ApplicationResponse>;
+    create(payload: CreateApplicationPayload): Promise<ApplicationResponse>;
+    update(applicationId: string, payload: UpdateApplicationPayload): Promise<ApplicationResponse>;
+}
+export {};

package/dist/resources/applications.js

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+import { createJsonApiCollectionSchema, createJsonApiResponseSchema, JsonApiResourceSchema, } from '../types/jsonApi.js';
+const regionSchema = z.enum([
+    'us-east-2',
+    'us-east-1',
+    'eu-central-1',
+    'eu-west-1',
+    'eu-west-2',
+    'ap-southeast-1',
+    'ap-southeast-2',
+    'ca-central-1',
+    'me-central-1',
+]);
+const repositorySchema = z
+    .object({
+    full_name: z.string(),
+    default_branch: z.string(),
+})
+    .partial();
+const applicationAttributesSchema = z
+    .object({
+    name: z.string(),
+    slug: z.string(),
+    region: z.string(),
+    slack_channel: z.string().nullable().optional(),
+    created_at: z.string(),
+    repository: repositorySchema.optional(),
+})
+    .passthrough();
+const applicationResourceSchema = JsonApiResourceSchema.extend({
+    type: z.literal('applications'),
+    attributes: applicationAttributesSchema,
+});
+const applicationResponseSchema = createJsonApiResponseSchema(applicationResourceSchema);
+const applicationCollectionSchema = createJsonApiCollectionSchema(applicationResourceSchema);
+const mapApplication = (resource) => {
+    const parsed = applicationResourceSchema.parse(resource);
+    const { attributes } = parsed;
+    return {
+        id: parsed.id,
+        name: attributes.name,
+        slug: attributes.slug,
+        region: attributes.region,
+        slackChannel: attributes.slack_channel ?? null,
+        createdAt: attributes.created_at,
+        repository: attributes.repository
+            ? {
+                fullName: attributes.repository.full_name,
+                defaultBranch: attributes.repository.default_branch,
+            }
+            : undefined,
+        raw: parsed,
+    };
+};
+const serializeApplicationList = (response) => ({
+    data: response.data.map(mapApplication),
+    included: response.included,
+    meta: response.meta,
+    links: response.links,
+});
+const serializeApplicationResponse = (response) => ({
+    data: mapApplication(response.data),
+    included: response.included,
+    meta: response.meta,
+    links: response.links,
+});
+export class ApplicationsResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(options) {
+        const query = {};
+        if (options?.include?.length) {
+            query.include = options.include.join(',');
+        }
+        if (options?.filter?.name) {
+            query['filter[name]'] = options.filter.name;
+        }
+        if (options?.filter?.region) {
+            query['filter[region]'] = options.filter.region;
+        }
+        if (options?.filter?.slug) {
+            query['filter[slug]'] = options.filter.slug;
+        }
+        if (options?.page?.number !== undefined) {
+            query['page[number]'] = options.page.number;
+        }
+        if (options?.page?.size !== undefined) {
+            query['page[size]'] = options.page.size;
+        }
+        const response = await this.client.request({
+            path: '/applications',
+            method: 'GET',
+            query,
+            schema: applicationCollectionSchema,
+        });
+        return serializeApplicationList(response);
+    }
+    async retrieve(applicationId, options) {
+        const query = options?.include?.length
+            ? { include: options.include.join(',') }
+            : undefined;
+        const response = await this.client.request({
+            path: `/applications/${applicationId}`,
+            method: 'GET',
+            query,
+            schema: applicationResponseSchema,
+        });
+        return serializeApplicationResponse(response);
+    }
+    async create(payload) {
+        const parsePayload = z
+            .object({
+            repository: z.string().min(1),
+            name: z.string().min(3).max(40),
+            region: regionSchema,
+        })
+            .parse(payload);
+        const response = await this.client.request({
+            path: '/applications',
+            method: 'POST',
+            json: parsePayload,
+            schema: applicationResponseSchema,
+        });
+        return serializeApplicationResponse(response);
+    }
+    async update(applicationId, payload) {
+        const parsedPayload = z
+            .object({
+            name: z.string().min(3).max(40).optional(),
+            slug: z.string().min(3).optional(),
+            defaultEnvironmentId: z.string().optional(),
+            repository: z.string().optional(),
+            slackChannel: z.string().nullable().optional(),
+        })
+            .strict()
+            .parse(payload);
+        const form = new FormData();
+        if (parsedPayload.name !== undefined) {
+            form.set('name', parsedPayload.name);
+        }
+        if (parsedPayload.slug !== undefined) {
+            form.set('slug', parsedPayload.slug);
+        }
+        if (parsedPayload.defaultEnvironmentId !== undefined) {
+            form.set('default_environment_id', parsedPayload.defaultEnvironmentId);
+        }
+        if (parsedPayload.repository !== undefined) {
+            form.set('repository', parsedPayload.repository);
+        }
+        if (parsedPayload.slackChannel !== undefined) {
+            form.set('slack_channel', parsedPayload.slackChannel ?? '');
+        }
+        const response = await this.client.request({
+            path: `/applications/${applicationId}`,
+            method: 'PATCH',
+            formData: form,
+            schema: applicationResponseSchema,
+        });
+        return serializeApplicationResponse(response);
+    }
+}

package/dist/resources/databases.d.ts

@@ -0,0 +1,74 @@
+import { HttpClient } from '../http/client.js';
+import { JsonApiResponse, JsonApiResource } from '../types/jsonApi.js';
+export interface DatabaseConnection {
+    hostname: string;
+    port: number;
+    protocol: string;
+    driver: string;
+    username: string;
+    password: string;
+    [key: string]: unknown;
+}
+export type DatabaseConfig = Record<string, unknown>;
+export interface Database {
+    id: string;
+    name: string;
+    type: string;
+    status: string;
+    region: string;
+    createdAt: string;
+    config: DatabaseConfig;
+    connection: DatabaseConnection;
+    raw: JsonApiResource;
+}
+export interface ListDatabasesOptions {
+    include?: Array<'schemas'>;
+    filter?: {
+        type?: string;
+        region?: string;
+        status?: string;
+    };
+    page?: {
+        number?: number;
+        size?: number;
+    };
+}
+export interface CreateDatabasePayload {
+    type: string;
+    name: string;
+    region: string;
+    config: DatabaseConfig;
+    clusterId?: number | null;
+}
+export interface DatabaseTypeField {
+    name: string;
+    type: string;
+    required: boolean;
+    nullable?: boolean;
+    description?: string;
+    min?: number;
+    max?: number;
+    enum?: string[];
+    example?: string;
+    raw: Record<string, unknown>;
+}
+export interface DatabaseTypeDefinition {
+    type: string;
+    label: string;
+    regions: string[];
+    configSchema: DatabaseTypeField[];
+    raw: Record<string, unknown>;
+}
+export interface DatabaseListResponse extends JsonApiResponse<Database[]> {
+}
+export interface DatabaseResponse extends JsonApiResponse<Database> {
+}
+export declare class DatabasesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(options?: ListDatabasesOptions): Promise<DatabaseListResponse>;
+    create(payload: CreateDatabasePayload): Promise<DatabaseResponse>;
+    retrieve(databaseId: string, options?: Pick<ListDatabasesOptions, 'include'>): Promise<DatabaseResponse>;
+    delete(databaseId: string): Promise<void>;
+    listTypes(): Promise<DatabaseTypeDefinition[]>;
+}