PHPackages                             timeax/dgp-services-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. timeax/dgp-services-sdk

ActiveLibrary[API Development](/categories/api)

timeax/dgp-services-sdk
=======================

Digital Growth Platform (DGP) Services SDK: capability-based contracts and typed request/response DTOs for Laravel-first service provider plugins (e.g., JustAnotherPanel), covering catalog, orders, status, refill, bulk ops, discovery, infra (auth/transport/retry/rate-limit/idempotency), and ops (health/audit/webhooks).

v0.0.2(5mo ago)026proprietaryPHPPHP ^8.2

Since Jan 25Pushed 2mo agoCompare

[ Source](https://github.com/timeax/dgp-services-sdk)[ Packagist](https://packagist.org/packages/timeax/dgp-services-sdk)[ RSS](/packages/timeax-dgp-services-sdk/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (2)Versions (6)Used By (0)

DGP Services SDK (Contracts + DTOs)
===================================

[](#dgp-services-sdk-contracts--dtos)

A **Laravel-first SDK** that defines the **service-driver contracts** your DGP plugins implement, plus the **typed DTO payloads** (Requests/Responses/Types) they exchange with the host.

This package is **not** your plugin system. Your plugin system already:

- installs/enables plugins
- collects config requirements + renders admin settings UI
- loads the plugin’s exported class (default export)
- passes a `dgp_handler` / runtime context (and the plugin can also read its own config)

**This SDK’s job** is to standardize what that exported class implements, so the Host can call any provider in a uniform way.

---

What this package enables
-------------------------

[](#what-this-package-enables)

### 1) Capability-based drivers

[](#1-capability-based-drivers)

Drivers implement only what they support (refill, cancel, bulk, fast-schema, etc.). The Host checks support via `instanceof` (and/or a capability map).

```
if ($driver instanceof OrderRefillContract) {
    // refill supported
}
```

### 2) Typed payloads (no magic arrays)

[](#2-typed-payloads-no-magic-arrays)

Every call uses typed **Request DTOs** and returns typed **Response DTOs**, wrapped in a consistent `Result`.

### 3) A clean “Driver layer”

[](#3-a-clean-driver-layer)

A registry + resolver + manager gives the Host a single way to:

- register available drivers
- resolve a driver by key
- call capability methods safely
- apply boundary wrappers (normalize errors, retry rules, rate-limit hints, etc.)

### 4) A baseline for panel-like providers

[](#4-a-baseline-for-panel-like-providers)

Using **JustAnotherPanel** as the reference model, the SDK targets common features:

services → order create/status → balance → optional cancel/refill/bulk.

---

Two-lane schema model (important)
---------------------------------

[](#two-lane-schema-model-important)

Providers can integrate at two schema levels:

### Lane A — Raw / Baseline (Host-owned normalization)

[](#lane-a--raw--baseline-host-owned-normalization)

- **Contract:** `ServicesCatalogContract` (**MUST**)
- **Returns:** `ServiceDefinition[]` (raw list)
- **Host job:** normalize raw services into the Host’s internal UI state (tags/fields/options/constraints) using Host rules.

This is the default and works for every provider.

### Lane B — Fast lane / Pre-normalized (Advanced)

[](#lane-b--fast-lane--pre-normalized-advanced)

- **Contract:** `ServiceSchemaContract` (**OPTIONAL / ADVANCED**)
- **Returns:** `ServiceProps` (TS-parity UI schema)
- **Host job:** **verify + clamp + cache** the schema, then serve to frontend.

This lane exists for sophisticated plugins that already compute the full UI schema.

> “Fast lane” does **not** mean blind trust. The Host validates and can reject/fallback to Lane A.

---

Decisions locked in
-------------------

[](#decisions-locked-in)

- **Result-first return strategy:** contract calls return `Result` so business failures (insufficient funds, rate-limited, invalid params) are first-class outcomes.
- **Exceptions are internal:** throw only for unrecoverable/system/invariant issues (transport, misconfiguration). `DriverManager` converts them to `Result` at the boundary.
- **TS parity for `ServiceProps`:** schema types must serialize into the *exact JSON keys* your React UI expects (snake\_case + camelCase as designed).
- **Pre-flight validation:** validate DTO invariants before any HTTP call.
- **Safe schema execution:** any “code-like” fields (e.g., quantity `eval` + `code`) must be treated as a **DSL / restricted expression**, never raw eval.

---

Critical implementation note: Lane B serialization keys
-------------------------------------------------------

[](#critical-implementation-note-lane-b-serialization-keys)

Your TS schema uses a mixed key convention (example: pricing\_role but quantityDefault).

Do not rely on automatic property names for Lane B. Types/Schema/\* should implement JsonSerializable (or your Arrayable) and explicitly output the correct keys:

```
public function jsonSerialize(): array {
    return array_filter([
        'id' => $this->id,
        'pricing_role' => $this->pricing_role,
        'quantityDefault' => $this->quantityDefault,
    ], fn ($v) => $v !== null);
}
```

---

Folder structure map (src)
--------------------------

[](#folder-structure-map-src)

```
src/
  DgpSdk.php
  DgpSdkServiceProvider.php

  Driver/
    DriverContext.php                   // runtime context: config + services (transport/logger/cache/clock)
    DriverRegistry.php                  // registered driver factories + metadata
    DriverResolver.php                  // resolve driver instance by key (registry + context)
    DriverManager.php                   // boundary wrapper: resolve + capability helpers + Result wrapping
    AbstractServiceDriver.php           // base class: core helpers + HealthCheck default

  Contracts/
    Catalog/
      ServicesCatalogContract.php       // CORE (MUST): raw service catalog (Lane A)
      ServiceInputSchemaContract.php    // OPTIONAL: minimal per-service input schema (Host still normalizes)
      ServiceSchemaContract.php         // OPTIONAL/ADVANCED: pre-normalized ServiceProps (Lane B fast lane)
      OperationInputSchemaContract      // OPTIONAL/ADVANCED

    Orders/
      OrderCreateContract.php           // CORE (MUST): place order
      OrderStatusContract.php           // CORE (MUST): status lookup
      OrderCancelContract.php           // OPTIONAL: cancel

    Balance/
      BalanceContract.php               // CORE (MUST for panel-like): provider balance

    Refill/
      OrderRefillContract.php           // OPTIONAL: create refill
      RefillStatusContract.php          // OPTIONAL: refill status

    Bulk/
      BulkOrderCreateContract.php       // OPTIONAL: bulk create
      BulkOrderStatusContract.php       // OPTIONAL: bulk status

    Subscription/
      SubscriptionContract.php          // OPTIONAL: subscription lifecycle

    DripFeed/
      DripFeedContract.php              // OPTIONAL: dripfeed lifecycle

    Infra/
      TransportContract.php             // HOST-PROVIDED transport interface (Laravel adapter lives in host)
      AuthStrategyContract.php          // OPTIONAL: driver-specific auth strategy
      ErrorNormalizerContract.php       // CORE (MUST): normalize provider errors into DgpError
      RetryPolicyContract.php           // OPTIONAL: retry/backoff decisions
      RateLimitPolicyContract.php       // OPTIONAL: rate limit hints/windows
      IdempotencyContract.php           // OPTIONAL: idempotency rules

    Discovery/
      CapabilitiesContract.php          // CORE (MUST): declare supported capabilities
      ServiceMapperContract.php         // OPTIONAL: host↔provider mapping helper

    Ops/
      HealthCheckContract.php           // CORE (MUST via AbstractServiceDriver): health/ping
      AuditTrailContract.php            // OPTIONAL: audit hooks
      WebhookIngestContract.php         // OPTIONAL: webhook parsing/verification

  Payloads/
    Requests/
      Catalog/
        ListServicesRequest.php
        GetServiceInputSchemaRequest.php
        GetServiceSchemaSnapshotRequest.php
        GetServiceSchemaForServiceRequest.php

      Orders/
        CreateOrderRequest.php
        GetOrderStatusRequest.php
        CancelOrderRequest.php

      Balance/
        GetBalanceRequest.php

      Refill/
        CreateRefillRequest.php
        GetRefillStatusRequest.php

      Bulk/
        BulkCreateOrdersRequest.php
        BulkGetOrderStatusRequest.php

      Subscription/
        CreateSubscriptionRequest.php
        GetSubscriptionStatusRequest.php
        CancelSubscriptionRequest.php

      DripFeed/
        CreateDripFeedRequest.php
        GetDripFeedStatusRequest.php
        CancelDripFeedRequest.php

      Infra/
        HttpRequestDto.php
        AuthApplyRequest.php
        NormalizeErrorRequest.php
        RetryDecisionRequest.php
        RateLimitHintRequest.php
        MakeIdempotencyKeyRequest.php

      Discovery/
        GetCapabilitiesRequest.php
        ResolveProviderServiceRequest.php

      Ops/
        HealthCheckRequest.php
        AuditRecordRequest.php
        ParseWebhookRequest.php

    Responses/
      Catalog/
        ListServicesResponse.php
        GetServiceInputSchemaResponse.php
        GetServiceSchemaSnapshotResponse.php
        GetServiceSchemaForServiceResponse.php

      Orders/
        CreateOrderResponse.php
        GetOrderStatusResponse.php
        CancelOrderResponse.php

      Balance/
        GetBalanceResponse.php

      Refill/
        CreateRefillResponse.php
        GetRefillStatusResponse.php

      Bulk/
        BulkCreateOrdersResponse.php
        BulkGetOrderStatusResponse.php

      Subscription/
        CreateSubscriptionResponse.php
        GetSubscriptionStatusResponse.php
        CancelSubscriptionResponse.php

      DripFeed/
        CreateDripFeedResponse.php
        GetDripFeedStatusResponse.php
        CancelDripFeedResponse.php

      Infra/
        HttpResponseDto.php
        AuthApplyResponse.php
        NormalizeErrorResponse.php
        RetryDecisionResponse.php
        RateLimitHintResponse.php
        MakeIdempotencyKeyResponse.php

      Discovery/
        GetCapabilitiesResponse.php
        ResolveProviderServiceResponse.php

      Ops/
        HealthCheckResponse.php
        AuditRecordResponse.php
        ParseWebhookResponse.php

  Types/
    Money.php
    Currency.php

    Service/
      ServiceDefinition.php             // raw baseline service item (strict core + meta bag)
      ServiceCategory.php
      ServiceTag.php
      ServiceInputSchema.php            // minimal per-service schema (Lane A helper)
      ServiceField.php
      ServiceFieldRule.php

    Schema/                             // TS-parity UI schema (Lane B: ServiceProps)
      ServiceProps.php
      Tag.php
      Field.php
      FieldOption.php
      ServiceFallback.php

      Ui/
        UiNode.php
        UiString.php
        UiNumber.php
        UiBoolean.php
        UiAnyOf.php
        UiArray.php
        UiObject.php

    Orders/
      OrderRef.php
      OrderStatus.php
      OrderStatusCode.php

    Balance/
      ProviderBalance.php

    Refill/
      RefillRef.php
      RefillStatus.php
      RefillStatusCode.php

    Subscription/
      SubscriptionRef.php
      SubscriptionStatus.php
      SubscriptionStatusCode.php

    DripFeed/
      DripFeedRef.php
      DripFeedStatus.php
      DripFeedStatusCode.php

    Infra/
      CapabilityMap.php
      ProviderRateLimit.php
      ProviderRateLimitWindow.php
      IdempotencyKey.php
      HttpMethod.php

    Ops/
      HealthState.php
      AuditRecord.php
      WebhookEvent.php
      WebhookEventType.php

  Support/
    Result.php                          // Result: success/failure wrapper
    DgpError.php
    DgpErrorCode.php

    Exceptions/
      DgpException.php
      TransportException.php
      AuthException.php
      ProviderException.php
      RateLimitedException.php
      ValidationException.php

    Hydration/
      HydratesFromArray.php             // trait for DTO ::fromArray(...)
      DtoHydrator.php                   // optional helper for host/controller DTO creation

    Validation/
      PayloadValidator.php              // pre-flight validation + schema verification

    Serialization/
      Arrayable.php
      Normalizes.php

    Testing/
      FakeTransport.php
      FakeClock.php
```

---

The flow this SDK expects
-------------------------

[](#the-flow-this-sdk-expects)

1. **Host** loads a plugin (your existing system) → obtains the exported driver class.
2. **Host** resolves a driver instance via `DriverResolver` / `DriverManager`.
3. **Host** calls capabilities (catalog/order/status/balance/etc.) via the driver interfaces.
4. **Driver** returns typed DTO responses wrapped in `Result`, with normalized errors.

---

Driver layer (src/Driver)
-------------------------

[](#driver-layer-srcdriver)

### `DriverRegistry`

[](#driverregistry)

Stores driver registrations:

- `driver_key` → factory/closure/class string
- optional metadata (label, version, category)

**Why:** central place to list available drivers and ensure uniqueness.

### `DriverResolver`

[](#driverresolver)

Creates driver instances from:

- registry entry
- runtime configuration (plugin settings, handler context, etc.)

**Why:** a single resolution path so the Host never does `new` directly.

### `DriverManager`

[](#drivermanager)

High-level façade used by the Host:

- `resolve($key)`
- convenience helpers for “must support X contract”
- safe wrappers for common patterns (error normalization, retry/backoff decisions)

**Why:** keeps Host code clean and consistent.

### `AbstractServiceDriver` (base class)

[](#abstractservicedriver-base-class)

An abstract driver with shared core behavior, including **Health** as a baseline.

Recommended built-ins:

- implements `HealthCheckContract`
- common helpers: `ok()`, `fail()`, `wrapExceptions()`
- convenience access to handler/config
- shared normalization utilities

**Why:** eliminates boilerplate and standardizes minimal behavior across drivers.

---

Contract map (what each does)
-----------------------------

[](#contract-map-what-each-does)

### Core contracts (MUST for a panel-like provider)

[](#core-contracts-must-for-a-panel-like-provider)

- **`ServicesCatalogContract`**

    - Raw services list: `ServiceDefinition[]`.
    - Enables discovery/mapping and Host-owned normalization (Lane A).
- **`OrderCreateContract`**

    - Place an order.
- **`OrderStatusContract`**

    - Fetch order status.
- **`BalanceContract`**

    - Fetch provider balance.
- **`CapabilitiesContract`**

    - Declare supported features (cancel/refill/bulk/schema/etc.).
- **`ErrorNormalizerContract`**

    - Normalize any provider error shape into `DgpError`.
- **`HealthCheckContract`** (provided by `AbstractServiceDriver`)

    - Quick health/ping/config sanity.

### Schema contracts (optional, but powerful)

[](#schema-contracts-optional-but-powerful)

- **`ServiceInputSchemaContract` (optional helper for Lane A)**

    - Returns minimal per-service fields (`ServiceInputSchema`).
    - The Host still owns final UI normalization.
- **`ServiceSchemaContract` (optional/advanced: Lane B fast lane)**

    - Returns **pre-normalized `ServiceProps`**.
    - Must support both shapes:

        - **Snapshot**: provider-wide schema for caching.
        - **Per-service**: focused schema for a single service.
    - Host validates/clamps; can fallback to Lane A if invalid.

### Common add-ons (optional)

[](#common-add-ons-optional)

- **Cancel:** `OrderCancelContract`
- **Refill:** `OrderRefillContract`, `RefillStatusContract`
- **Bulk:** `BulkOrderCreateContract`, `BulkOrderStatusContract`
- **Subscription:** `SubscriptionContract`
- **Drip feed:** `DripFeedContract`

### Infra policy hooks (optional)

[](#infra-policy-hooks-optional)

- **Transport:** `TransportContract` (host-provided interface)
- **Auth:** `AuthStrategyContract`
- **Retry:** `RetryPolicyContract`
- **Rate limit:** `RateLimitPolicyContract`
- **Idempotency:** `IdempotencyContract`

### Ops hooks (optional)

[](#ops-hooks-optional)

- **Audit:** `AuditTrailContract`
- **Webhooks:** `WebhookIngestContract`

---

DTOs (Payloads + Types)
-----------------------

[](#dtos-payloads--types)

### Requests (`src/Payloads/Requests`)

[](#requests-srcpayloadsrequests)

Input DTOs passed by the Host.

Rules:

- explicit fields, no magic arrays
- allow `meta` only when intentionally flexible

### Responses (`src/Payloads/Responses`)

[](#responses-srcpayloadsresponses)

Typed results returned by drivers.

Rules:

- canonical normalized data
- optional `meta` for provider-specific extras

### Shared Types (`src/Types`)

[](#shared-types-srctypes)

Reusable building blocks shared across payloads.

Key split:

- `Types/Service/*` → raw service list + minimal input schema (Lane A)
- `Types/Schema/*` → TS-parity `ServiceProps` UI schema (Lane B)

---

Support layer (`src/Support`)
-----------------------------

[](#support-layer-srcsupport)

### Result + Errors

[](#result--errors)

A consistent return model:

- `Result` — success/failure wrapper
- `DgpError` + `DgpErrorCode` — canonical error representation

### Exceptions

[](#exceptions)

Typed exceptions for internal ergonomics (`TransportException`, `AuthException`, etc.). Drivers can throw internally, while `DriverManager` wraps/normalizes into `Result`.

### Validation / Serialization / Testing

[](#validation--serialization--testing)

- pre-flight validation helpers
- schema verification helpers (Lane B)
- serialization interfaces
- fakes (`FakeTransport`, `FakeClock`) for unit tests

---

Implementation plan (what we do next, in order)
-----------------------------------------------

[](#implementation-plan-what-we-do-next-in-order)

### Step 1 — Foundation (everything depends on this)

[](#step-1--foundation-everything-depends-on-this)

- `Result` + `DgpError` + `DgpErrorCode`
- `DriverContext` + `DriverManager` boundary wrapping
- `PayloadValidator` for pre-flight + schema verification

### Step 2 — Raw lane MVP (most providers)

[](#step-2--raw-lane-mvp-most-providers)

- `ServicesCatalogContract` + `ServiceDefinition`
- `OrderCreateContract`, `OrderStatusContract`, `BalanceContract`
- `ErrorNormalizerContract`, `CapabilitiesContract`
- health check baseline

### Step 3 — Optional helpers

[](#step-3--optional-helpers)

- `ServiceInputSchemaContract` + `ServiceInputSchema`
- mapping helpers if needed

### Step 4 — Fast lane (advanced)

[](#step-4--fast-lane-advanced)

- `Types/Schema/*` (TS-parity `ServiceProps`)
- `ServiceSchemaContract` snapshot + per-service
- strict validation + versioning + clamp rules

### Step 5 — JAM add-ons

[](#step-5--jam-add-ons)

- cancel, refill, bulk

### Step 6 — Remaining optional capabilities

[](#step-6--remaining-optional-capabilities)

- subscription, dripfeed
- infra hooks (retry/rate-limit/idempotency)
- ops hooks (audit/webhooks)

---

What this package deliberately does NOT do
------------------------------------------

[](#what-this-package-deliberately-does-not-do)

- install/enable/disable plugins (your system already does this)
- store plugin settings (your system already does this)
- define host database schema
- enforce UI implementation details (it only defines contracts + typed shapes)

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance79

Regular maintenance activity

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

157d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/105345335?v=4)[David Okpako](/maintainers/timeax)[@timeax](https://github.com/timeax)

---

Top Contributors

[![timeax](https://avatars.githubusercontent.com/u/105345335?v=4)](https://github.com/timeax "timeax (24 commits)")[![google-labs-jules[bot]](https://avatars.githubusercontent.com/in/842251?v=4)](https://github.com/google-labs-jules[bot] "google-labs-jules[bot] (1 commits)")

### Embed Badge

![Health badge](/badges/timeax-dgp-services-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/timeax-dgp-services-sdk/health.svg)](https://phpackages.com/packages/timeax-dgp-services-sdk)
```

###  Alternatives

[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.6k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)[rapidez/core

Rapidez Core

1823.5k72](/packages/rapidez-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)