# LiBilling ApisCP Provisioning Module

ApisCP (apnscp) provisioning module for LiBilling. Provides automated hosting account lifecycle management via the ApisCP SOAP API.

## Features

- **Account Lifecycle**: Create, suspend, unsuspend, terminate hosting accounts
- **Single Sign-On**: Customer SSO and admin impersonation via session hijacking
- **Password Management**: Change hosting account passwords via the API
- **Package Changes**: Upgrade/downgrade plans via `admin_edit_site` with plan reset
- **Usage Sync**: Pull disk and bandwidth usage/limits from the server
- **Quick Shortcuts**: Deep links into ApisCP panel (file manager, email, databases, terminal, etc.)
- **Service Info**: Display control panel URL, shared IP, and plan name on service pages
- **Deferred Cancellation**: Suspend cancelled accounts with a grace period before permanent deletion

## Configuration

Publish the config file:

```bash
php artisan vendor:publish --tag=libilling-apiscp
```

### Config Options

| Key | Env | Default | Description |
|---|---|---|---|
| `deferred_cancellation_enabled` | `APISCP_DEFERRED_CANCELLATION_ENABLED` | `true` | Enable deferred cancellation (suspend instead of immediate delete) |
| `deferred_cancellation_reason` | `APISCP_DEFERRED_REASON` | `Deferred Account Cancellation` | Suspension reason used to identify deferred cancellations |
| `deferred_cancellation_days` | `APISCP_DEFERRED_DAYS` | `30` | Days to keep suspended accounts before permanent deletion |

### API Connection

The ApisCP API connection is configured per-server in the LiBilling admin panel:

- **Hostname**: The ApisCP server hostname
- **Port**: Default `2083`
- **Password**: The API key from ApisCP (Dev > API Keys)

For development with self-signed SSL certificates, set `APISCP_VERIFY_SSL=false` in your `.env` (configured in the `laravel-apiscp-api` package).

## Deferred Cancellation

When enabled (default), terminated services are **suspended** on the server with a configurable reason instead of being immediately deleted. This provides a grace period for:

- Customer changes their mind and reverses the cancellation
- Staff recovery of accidentally cancelled accounts
- Data retention compliance

### How It Works

1. Customer cancels a service (immediate or end-of-period)
2. LiBilling core sets the service status to Cancelled/Terminated
3. The `terminate()` method suspends the account with the configured reason
4. A daily scheduled command (`apiscp:purge-deferred-cancellations`) permanently deletes accounts that have been suspended for longer than the configured grace period
5. If the customer reverses the cancellation during the grace period, `unsuspend()` reactivates the account

### Disabling Deferred Cancellation

Set `APISCP_DEFERRED_CANCELLATION_ENABLED=false` in your `.env`. The `terminate()` method will immediately call `admin_delete_site()` instead.

## Scheduled Commands

| Command | Schedule | Description |
|---|---|---|
| `apiscp:purge-deferred-cancellations` | Daily | Delete suspended accounts past the grace period |

This command is automatically registered and scheduled by the module's service provider.

## Knowledgebase Articles

The module ships a starter set of customer-facing KB articles covering the ApisCP control panel, login, files, email, databases, etc. Install them once after setup:

```bash
php artisan libilling:apiscp-install-kb
```

Pass `--force` to re-import on top of an existing install (replaces the seeded category and articles):

```bash
php artisan libilling:apiscp-install-kb --force
```

The articles land under a top-level KB category named after `libilling-apiscp.whitelabel_name` (default `ApisCP`), so you can rebrand without forking the package. The seeder lives at `LithiumHosting\LiBilling\ApisCp\Seeders\ApiscpKbSeeder` if you want to call it directly from a custom seeder.

## Capabilities

The module declares these capabilities via `supports()`:

- `sso` / `impersonate` -- Single sign-on for customers and admin
- `change_password`: Password changes via API
- `suspend` / `unsuspend` / `terminate` -- Account lifecycle
- `deferred_cancellation`: Present when deferred cancellation is enabled
- `usage_stats`: Disk and bandwidth sync via `getUsageData()`
- `shortcuts`: Deep links into ApisCP control panel apps
- `service_info`: Control panel URL, shared IP, plan name

## Dependencies

- `lithiumhosting/laravel-apiscp-api`: Low-level SOAP client for ApisCP

## Installation

```bash
composer require libilling/libilling-apiscp
```

## License

LiBilling is (C) Lithium Holdings, LLC. All components except for third-party modules
and select packages with their own license are licensed under
a Commercial License. Contact licensing@lithiumholdings.com for licensing enquiries. Any dissemination of
material herein is prohibited without expressed written consent of Lithium Holdings.

This package, libilling-apiscp is licensed under The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

## Is it any good?

Yes.

_When people first hear about a new product, they frequently ask if it is any good. A Hacker News user
[remarked](https://news.ycombinator.com/item?id=3067434):_

> Note to self: Starting immediately, all raganwald projects will have a "Is it any good?" section in the readme, and
> the answer shall be "yes.".
