@studiometa/forge-sdk 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,178 @@
+# @studiometa/forge-sdk
+
+[![npm version](https://img.shields.io/npm/v/@studiometa/forge-sdk?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/forge-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat&colorB=3e63dd&colorA=414853)](https://opensource.org/licenses/MIT)
+
+**The missing TypeScript SDK for Laravel Forge.** Fluent, chainable, fully-typed API client.
+
+The official Forge SDK exists only in PHP (`laravel/forge-sdk`). This package fills the gap with a modern TypeScript SDK that mirrors the Forge URL structure in a fluent, chainable API.
+
+## Installation
+
+```bash
+npm install @studiometa/forge-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Forge } from "@studiometa/forge-sdk";
+
+const forge = new Forge("your-api-token");
+
+// List all servers
+const servers = await forge.servers.list();
+
+// Get a specific server
+const server = await forge.servers.get(123);
+
+// Deploy a site
+await forge.server(123).site(456).deploy();
+
+// Get environment variables
+const env = await forge.server(123).site(456).env.get();
+
+// Update environment
+await forge.server(123).site(456).env.update("APP_ENV=production\nAPP_DEBUG=false");
+```
+
+## API Reference
+
+### Servers
+
+```typescript
+// Collection operations
+forge.servers.list()                    // List all servers
+forge.servers.get(id)                   // Get a server
+forge.servers.create({ ... })           // Create a server
+forge.servers.update(id, { ... })       // Update a server
+forge.servers.delete(id)                // Delete a server
+forge.servers.reboot(id)                // Reboot a server
+
+// Resource with nested access
+forge.server(id).get()                  // Get server details
+forge.server(id).reboot()               // Reboot server
+forge.server(id).delete()               // Delete server
+forge.server(id).sites.list()           // List sites on server
+forge.server(id).databases.list()       // List databases
+forge.server(id).daemons.list()         // List daemons
+```
+
+### Sites
+
+```typescript
+// Collection operations
+forge.server(id).sites.list()           // List all sites
+forge.server(id).sites.get(siteId)      // Get a site
+forge.server(id).sites.create({ domain: 'example.com', project_type: 'php' })
+forge.server(id).sites.update(siteId, { ... })
+forge.server(id).sites.delete(siteId)
+
+// Resource with nested access
+forge.server(id).site(siteId).get()         // Get site details
+forge.server(id).site(siteId).deploy()      // Deploy site
+forge.server(id).site(siteId).delete()      // Delete site
+forge.server(id).site(siteId).env.get()     // Get .env content
+forge.server(id).site(siteId).env.update('...')  // Update .env
+forge.server(id).site(siteId).nginx.get()   // Get Nginx config
+forge.server(id).site(siteId).nginx.update('...')  // Update Nginx
+```
+
+### Deployments
+
+```typescript
+forge.server(id).site(siteId).deployments.list(); // List deployments
+forge.server(id).site(siteId).deployments.get(depId); // Get deployment
+forge.server(id).site(siteId).deployments.output(depId); // Get output
+forge.server(id).site(siteId).deployments.script(); // Get deploy script
+forge.server(id).site(siteId).deployments.updateScript("npm run build");
+```
+
+### Certificates
+
+```typescript
+forge.server(id).site(siteId).certificates.list();
+forge.server(id).site(siteId).certificates.get(certId);
+forge.server(id).site(siteId).certificates.create({ type: "new", domain: "example.com" });
+forge.server(id).site(siteId).certificates.letsEncrypt(["example.com"]);
+forge.server(id).site(siteId).certificates.activate(certId);
+forge.server(id).site(siteId).certificates.delete(certId);
+```
+
+### Databases
+
+```typescript
+forge.server(id).databases.list();
+forge.server(id).databases.get(dbId);
+forge.server(id).databases.create({ name: "myapp", user: "admin", password: "secret" });
+forge.server(id).databases.delete(dbId);
+```
+
+### Daemons (Background Processes)
+
+```typescript
+forge.server(id).daemons.list();
+forge.server(id).daemons.get(daemonId);
+forge.server(id).daemons.create({ command: "php artisan queue:work", user: "forge" });
+forge.server(id).daemons.restart(daemonId);
+forge.server(id).daemons.delete(daemonId);
+```
+
+### User
+
+```typescript
+const user = await forge.user();
+console.log(user.name, user.email);
+```
+
+## Comparison with PHP SDK
+
+| Feature         | PHP (`laravel/forge-sdk`) | TypeScript (`@studiometa/forge-sdk`) |
+| --------------- | ------------------------- | ------------------------------------ |
+| Language        | PHP                       | TypeScript/JavaScript                |
+| API style       | Method calls              | Fluent chainable                     |
+| Type safety     | PHPDoc                    | Full TypeScript types                |
+| Node.js support | ❌                        | ✅ Native                            |
+| GitHub Actions  | Via PHP setup             | Native `npm install`                 |
+| Rate limiting   | Manual                    | Built-in (60 req/min)                |
+| Error types     | Generic                   | Typed `ForgeApiError`                |
+
+## Testing
+
+The SDK supports dependency injection for testing:
+
+```typescript
+const mockFetch = async (url, init) => {
+  return new Response(JSON.stringify({ servers: [] }), {
+    headers: { "content-type": "application/json" },
+  });
+};
+
+const forge = new Forge("test-token", { fetch: mockFetch });
+const servers = await forge.servers.list(); // Uses mock fetch
+```
+
+## GitHub Actions Example
+
+```typescript
+import { Forge } from "@studiometa/forge-sdk";
+
+const forge = new Forge(process.env.FORGE_API_TOKEN);
+
+// Deploy after successful CI
+const sites = await forge.server(123).sites.list();
+const site = sites.find((s) => s.name === "myapp.com");
+if (site) {
+  await forge.server(123).site(site.id).deploy();
+  console.log("Deployment triggered!");
+}
+```
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch`)
+- **Laravel Forge account** with API token
+
+## License
+
+MIT © [Studio Meta](https://www.studiometa.fr)

package/dist/forge.d.ts

@@ -0,0 +1,93 @@
+import type { ForgeOptions, ForgeUser } from "@studiometa/forge-api";
+import { HttpClient } from "@studiometa/forge-api";
+import { ServersCollection, ServerResource } from "./resources/servers.ts";
+import { RecipesCollection } from "./resources/recipes.ts";
+/**
+ * Laravel Forge TypeScript SDK.
+ *
+ * Provides a fluent, chainable API for managing Laravel Forge servers,
+ * sites, deployments, and more.
+ *
+ * @example
+ * ```ts
+ * import { Forge } from '@studiometa/forge-sdk';
+ *
+ * const forge = new Forge('your-api-token');
+ *
+ * // List all servers
+ * const servers = await forge.servers.list();
+ *
+ * // Deploy a site
+ * await forge.server(123).site(456).deploy();
+ *
+ * // Get environment variables
+ * const env = await forge.server(123).site(456).env.get();
+ *
+ * // Manage databases
+ * const dbs = await forge.server(123).databases.list();
+ * ```
+ */
+export declare class Forge {
+    /** @internal */
+    readonly client: HttpClient;
+    /** Server operations (list, get, create, update, delete, reboot). */
+    readonly servers: ServersCollection;
+    /** Recipe operations (list, get, create, delete, run). */
+    readonly recipes: RecipesCollection;
+    /**
+     * Create a new Forge SDK instance.
+     *
+     * @param token Your Laravel Forge API token.
+     * @param options Optional configuration (custom fetch, base URL, rate limiting).
+     *
+     * @example
+     * ```ts
+     * // Basic usage
+     * const forge = new Forge('your-api-token');
+     *
+     * // With custom options
+     * const forge = new Forge('your-api-token', {
+     *   baseUrl: 'https://custom-forge-instance.com/api/v1',
+     * });
+     *
+     * // With mock fetch for testing
+     * const forge = new Forge('test-token', { fetch: mockFetch });
+     * ```
+     */
+    constructor(token: string, options?: ForgeOptions);
+    /**
+     * Access a specific server by ID, with nested resources.
+     *
+     * Returns a `ServerResource` that provides access to sites, databases,
+     * daemons, and other server-level resources.
+     *
+     * @param serverId The server ID.
+     *
+     * @example
+     * ```ts
+     * // List sites on a server
+     * const sites = await forge.server(123).sites.list();
+     *
+     * // Access a specific site
+     * const site = await forge.server(123).site(456);
+     *
+     * // Deploy a site
+     * await forge.server(123).site(456).deploy();
+     *
+     * // Manage databases
+     * const dbs = await forge.server(123).databases.list();
+     * ```
+     */
+    server(serverId: number): ServerResource;
+    /**
+     * Get the currently authenticated user.
+     *
+     * @example
+     * ```ts
+     * const user = await forge.user();
+     * console.log(user.name, user.email);
+     * ```
+     */
+    user(): Promise<ForgeUser>;
+}
+//# sourceMappingURL=forge.d.ts.map

package/dist/forge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.d.ts","sourceRoot":"","sources":["../src/forge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAgB,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,KAAK;IAChB,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAE5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAEpC,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAMjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAIxC;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,SAAS,CAAC;CAIjC"}

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { Forge } from "./forge.ts";
+export { BaseCollection } from "./resources/base.ts";
+export { AsyncPaginatedIterator } from "./pagination.ts";
+export type { PageFetcher } from "./pagination.ts";
+export { BackupsCollection } from "./resources/backups.ts";
+export type { BackupConfigListOptions } from "./resources/backups.ts";
+export { CertificatesCollection } from "./resources/certificates.ts";
+export type { CertificateListOptions } from "./resources/certificates.ts";
+export { CommandsCollection } from "./resources/commands.ts";
+export type { CommandListOptions } from "./resources/commands.ts";
+export { DaemonsCollection } from "./resources/daemons.ts";
+export type { DaemonListOptions } from "./resources/daemons.ts";
+export { DatabasesCollection } from "./resources/databases.ts";
+export type { DatabaseListOptions } from "./resources/databases.ts";
+export { DatabaseUsersCollection } from "./resources/database-users.ts";
+export type { DatabaseUserListOptions } from "./resources/database-users.ts";
+export { DeploymentsCollection } from "./resources/deployments.ts";
+export type { DeploymentListOptions } from "./resources/deployments.ts";
+export { FirewallRulesCollection } from "./resources/firewall-rules.ts";
+export type { FirewallRuleListOptions } from "./resources/firewall-rules.ts";
+export { MonitorsCollection } from "./resources/monitors.ts";
+export type { MonitorListOptions } from "./resources/monitors.ts";
+export { NginxTemplatesCollection } from "./resources/nginx-templates.ts";
+export type { NginxTemplateListOptions } from "./resources/nginx-templates.ts";
+export { RecipesCollection } from "./resources/recipes.ts";
+export type { RecipeListOptions, RunRecipeOptions } from "./resources/recipes.ts";
+export { RedirectRulesCollection } from "./resources/redirect-rules.ts";
+export type { RedirectRuleListOptions } from "./resources/redirect-rules.ts";
+export { ScheduledJobsCollection } from "./resources/scheduled-jobs.ts";
+export type { ScheduledJobListOptions } from "./resources/scheduled-jobs.ts";
+export { SecurityRulesCollection } from "./resources/security-rules.ts";
+export type { SecurityRuleListOptions } from "./resources/security-rules.ts";
+export { ServersCollection, ServerResource } from "./resources/servers.ts";
+export type { ServerListOptions } from "./resources/servers.ts";
+export { SshKeysCollection } from "./resources/ssh-keys.ts";
+export type { SshKeyListOptions } from "./resources/ssh-keys.ts";
+export { SiteEnvResource, SiteNginxResource, SiteResource, SitesCollection, } from "./resources/sites.ts";
+export type { SiteListOptions } from "./resources/sites.ts";
+export type { CreateBackupConfigData, CreateCertificateData, CreateCommandData, CreateDaemonData, CreateDatabaseData, CreateDatabaseUserData, CreateFirewallRuleData, CreateMonitorData, CreateNginxTemplateData, CreateRecipeData, CreateRedirectRuleData, CreateScheduledJobData, CreateSecurityRuleData, CreateServerData, CreateSiteData, CreateSshKeyData, ForgeBackup, ForgeBackupConfig, ForgeCertificate, ForgeCommand, ForgeDaemon, ForgeDatabase, ForgeDatabaseUser, ForgeDeployment, ForgeFirewallRule, ForgeMonitor, ForgeNginxTemplate, ForgeOptions, ForgeRecipe, ForgeRedirectRule, ForgeScheduledJob, ForgeSecurityRule, ForgeServer, ForgeSite, ForgeSshKey, ForgeUser, } from "@studiometa/forge-api";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}