writetainer-lib 25.12.27-dev.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Erick Tran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# Writetainer-Lib
+
+A Portainer API accessibility library for Node.js, written in TypeScript. This library provides a convenient wrapper around the Portainer API, allowing you to easily interact with your Portainer instance to manage environments, stacks, and containers.
+
+## Features
+
+- **Authentication**: Easy authentication using Portainer API tokens
+- **Environment Management**: Fetch and manage Portainer environments (endpoints)
+- **Stack Management**: Create, retrieve, start, stop, update, and delete stacks
+- **Container Management**: Full container lifecycle management (start, stop, restart, remove, etc.)
+- **Factory Pattern**: High-level factory methods for easy stack and container creation
+- **TypeScript Support**: Fully typed interfaces for better development experience
+- **Logging**: Built-in logging with debug package integration
+
+## Installation
+
+```bash
+npm install writetainer-lib
+```
+
+## Prerequisites
+
+Create a `.env` file in your project root with the following variables:
+
+```env
+PORTAINER_URL=https://your-portainer-instance.com
+PORTAINER_API_KEY=your-api-token-here
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { PortainerApi, PortainerFactory, logInfo } from 'writetainer-lib';
+
+// Get the singleton instance of PortainerApi
+const api = PortainerApi.getInstance();
+
+// Check connection status
+const isConnected = await api.getStatus();
+logInfo('Connected:', isConnected);
+
+// Get all stacks
+const stacks = await api.getStacks();
+logInfo('Stacks:', stacks);
+
+// Get all containers
+const containers = await api.getContainers(true);
+logInfo('Containers:', containers);
+```
+
+### Creating Stacks with Factory
+
+```typescript
+import { PortainerFactory } from 'writetainer-lib';
+
+const factory = PortainerFactory.getInstance();
+
+const stackConfig = {
+    Name: "my-app-stack",
+    ComposeFile: `
+services:
+  web:
+    image: nginx:latest
+    ports:
+      - "80:80"
+    restart: unless-stopped
+    `,
+    Env: [
+        { name: "ENVIRONMENT", value: "production" }
+    ]
+};
+
+// Create the stack
+const stack = await factory.createStack(stackConfig);
+```
+
+### Container Management
+
+```typescript
+import { PortainerApi } from 'writetainer-lib';
+
+const api = PortainerApi.getInstance();
+
+// Start a container
+await api.handleContainer({
+    action: 'start',
+    containerId: 'container-id-here',
+    environmentId: 1
+});
+
+// Stop a container
+await api.handleContainer({
+    action: 'stop',
+    containerId: 'container-id-here'
+});
+
+// Remove a container with options
+await api.handleContainer({
+    action: 'remove',
+    containerId: 'container-id-here',
+    options: {
+        force: true,
+        removeVolumes: true
+    }
+});
+
+// Restart a container with custom timeout
+await api.handleContainer({
+    action: 'restart',
+    containerId: 'container-id-here',
+    options: {
+        timeout: 30000 // 30 seconds
+    }
+});
+```
+
+### Stack Operations
+
+```typescript
+import { PortainerApi } from 'writetainer-lib';
+
+const api = PortainerApi.getInstance();
+
+// Start a stack
+await api.startStack(stackId, environmentId);
+
+// Stop a stack
+await api.stopStack(stackId, environmentId);
+
+// Update a stack with new compose content
+await api.updateStack(stackId, newComposeContent, environmentId, true);
+
+// Redeploy a stack (stop, pull, start)
+await api.redeployStack(stackId, environmentId);
+
+// Delete a stack
+await api.deleteStack(stackId, environmentId);
+```
+
+### Environment Management
+
+```typescript
+import { PortainerApi, getFirstEnvironmentId } from 'writetainer-lib';
+
+const api = PortainerApi.getInstance();
+
+// Get all environments
+const environments = await api.getEnvironments();
+
+// Get details of a specific environment
+const envDetails = await api.getEnvironmentDetails(environmentId);
+
+// Get first environment ID
+const firstEnvId = await getFirstEnvironmentId();
+```
+
+### Resource Fetching
+
+```typescript
+import { PortainerApi } from 'writetainer-lib';
+
+const api = PortainerApi.getInstance();
+
+// Get all containers (including stopped ones)
+const allContainers = await api.getContainers(true);
+
+// Get running containers only
+const runningContainers = await api.getContainers(false);
+
+// Get container details
+const containerDetails = await api.getContainerDetails('container-id');
+
+// Get container stats
+const stats = await api.getContainerStats('container-id');
+
+// Get images
+const images = await api.getImages(environmentId);
+```
+
+### Utility Functions
+
+```typescript
+import { 
+    getStackByName, 
+    getStackById,
+    getContainerByDetails,
+    verifyStackCreation,
+    verifyContainerCreation 
+} from 'writetainer-lib';
+
+// Find a stack by name
+const stack = await getStackByName('my-stack-name');
+
+// Find a stack by ID
+const stack = await getStackById(123, environmentId);
+
+// Find container by image or label
+const container = await getContainerByDetails({
+    image: 'nginx:latest'
+});
+
+// Verify stack creation
+const isVerified = await verifyStackCreation('my-stack', 5000, 3);
+
+// Verify container creation
+const isRunning = await verifyContainerCreation('my-container', 5000);
+```
+
+## API Reference
+
+### Main Classes
+
+#### `PortainerApi`
+Singleton class that provides access to all Portainer API operations.
+
+**Methods:**
+- `getInstance(environmentId?: number | null)` - Get singleton instance
+- `getEnvironments()` - Fetch all environments
+- `getEnvironmentDetails(environmentId)` - Get environment details
+- `getStacks()` - Get all stacks
+- `getContainers(includeAll, environmentId?)` - Get containers
+- `getContainerDetails(identifier, environmentId?)` - Get container details
+- `getContainerStats(identifier, environmentId?)` - Get container stats
+- `getImages(environmentId?)` - Get images
+- `getStatus(environmentId?)` - Get system status
+- `handleContainer(controls)` - Execute container actions
+- `startStack(stackId, environmentId?)` - Start a stack
+- `stopStack(stackId, environmentId?)` - Stop a stack
+- `updateStack(stackId, composeContent, environmentId?, pullImage?)` - Update a stack
+- `redeployStack(stackId, environmentId?)` - Redeploy a stack
+- `deleteStack(stackId, environmentId?)` - Delete a stack
+- `cleanupExistingContainer(containerName, environmentId?)` - Cleanup a container
+- `ensureEnvId()` - Ensure environment ID is set
+
+#### `PortainerFactory`
+Singleton factory class for creating resources with validation.
+
+**Methods:**
+- `getInstance(environmentId?: number | null)` - Get singleton instance
+- `createStack(stackData, maxRetryCount?, timeoutMs?)` - Create a new stack
+- `createContainer(containerData, maxRetryCount?, timeoutMs?)` - Create a new container
+
+#### `PortainerAuth`
+Singleton class for authentication management.
+
+**Properties:**
+- `axiosInstance` - Configured axios instance
+- `isValidated` - Authentication validation status
+- `PortainerUrl` - Portainer URL
+
+**Methods:**
+- `getInstance()` - Get singleton instance
+
+### Type Definitions
+
+```typescript
+interface PortainerEnvironment {
+    Id: number;
+    Name: string;
+}
+
+interface PortainerStack {
+    Id: number;
+    Name: string;
+    EndpointId: number;
+}
+
+interface PortainerContainer {
+    Id: string;
+    Names: string[];
+    Image: string;
+    Labels: { [key: string]: string };
+    State: string;
+    Status: string;
+    // ... additional properties
+}
+
+interface PortainerImage {
+    Id: string;
+    RepoTags: string[];
+    Created: number;
+    Size: number;
+}
+
+interface PortainerStackContent {
+    Name: string;
+    ComposeFile: string | any;
+    Env?: Array<{ name: string; value: string }>;
+    FromAppTemplate?: boolean;
+}
+```
+
+## Logging
+
+The library uses the `debug` package for logging. To enable logs:
+
+```bash
+# Enable all logs
+DEBUG=portainer-api:* node your-app.js
+
+# Enable only info logs
+DEBUG=portainer-api:info node your-app.js
+
+# Enable error and warning logs
+DEBUG=portainer-api:error,portainer-api:warn node your-app.js
+```
+
+You can also use the built-in logging functions:
+
+```typescript
+import { logInfo, logWarn, logError } from 'writetainer-lib';
+
+logInfo('This is an info message');
+logWarn('This is a warning');
+logError('This is an error', errorObject);
+```
+
+#### Get Stacks
+
+```typescript
+const stacks = await client.getStacks();
+console.log(stacks);
+```
+
+#### Get Containers
+
+Fetch all containers (running and stopped) for the default environment.
+
+```typescript
+const containers = await client.getContainers(true);
+console.log(containers);
+```
+
+#### Test Connection
+
+```typescript
+const isConnected = await client.testConnection();
+if (isConnected) {
+    console.log('Connected to Portainer!');
+}
+```
+
+## API Reference
+
+### `PortainerApiClient`
+
+#### Constructor
+`new PortainerApiClient(portainerUrl: string, apiToken: string, environmentId?: number | null)`
+
+#### Methods
+
+- `getEnvironments(): Promise<PortainerEnvironment[]>`
+  - Fetches a list of all Portainer environments.
+
+- `getEnvironment(environmentId: number): Promise<PortainerEnvironment>`
+  - Fetches details of a specific environment.
+
+- `getStacks(): Promise<PortainerStack[]>`
+  - Fetches a list of all stacks.
+
+- `getContainers(includeAll: boolean): Promise<PortainerContainer[] | undefined>`
+  - Fetches a list of containers for the current environment.
+  - `includeAll`: Set to `true` to include stopped containers.
+
+- `testConnection(): Promise<boolean>`
+  - Tests the connection to the Portainer API.
+
+- `DefaultEnvironmentId` (Getter/Setter)
+  - Get or set the default environment ID used for container operations.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "writetainer-lib",
+  "version": "25.12.27-dev.9",
+  "description": "A TypeScript library for interacting with the Portainer API to manage Docker containers and stacks programmatically.",
+  "homepage": "https://github.com/enVId-tech/Writetainer-Lib#readme",
+  "bugs": {
+    "url": "https://github.com/enVId-tech/Writetainer-Lib/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enVId-tech/Writetainer-Lib.git"
+  },
+  "license": "MIT",
+  "author": "envid-tech",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsc",
+    "ncu": "npx npm-check-updates -u && npm install"
+  },
+  "dependencies": {
+    "axios": "^1.13.6",
+    "debug": "^4.4.3",
+    "dotenv": "^17.3.1",
+    "typescript": "^5.9.3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/debug": "^4.1.13",
+    "@types/node": "^25.5.0",
+    "vitest": "^4.1.0"
+  },
+  "type": "module"
+}