# YAS SMPP Integration and Acceptance Guide

The tenant-facing surface is governed by [API_V1_CONTRACT.md](api/API_V1_CONTRACT.md) and the authoritative [OpenAPI 3.1 document](api/openapi.yaml). YAS evidence remains internal unless those contracts explicitly expose it.

## Status

The repository contains a validated YAS SMPP connection configuration, bind diagnostic, live single-message diagnostic, outbound execution components, inbound `deliver_sm` processing, DLR correlation, status projection, and terminal webhooks. Live endpoint values and YAS acceptance evidence are not stored in documentation and remain to be confirmed.

Do not treat this guide as YAS approval. Record external confirmation in [ACCEPTANCE_CHECKLIST.md](ACCEPTANCE_CHECKLIST.md).

## Exact implemented configuration

Use operator-supplied values for placeholders. Do not commit the resulting environment file.

| Environment key | Implemented purpose | Repository default or required value |
| --- | --- | --- |
| `SMPP_CONNECTION` | Default SMPP connection key | `yas` |
| `SMPP_CONNECTION_YAS_NAME` | Provider/connection code | `yas` |
| `SMPP_HOST` | Primary hostname or IP | `<YAS_HOST>` |
| `SMPP_BACKUP_HOST` | Optional backup hostname or IP | Empty unless YAS supplies one |
| `SMPP_PORT` | TCP port | `<YAS_PORT>`; no usable default |
| `SMPP_SYSTEM_ID` | Bind system ID | `<YAS_SYSTEM_ID>` |
| `SMPP_PASSWORD` | Bind password | `<YAS_PASSWORD>` |
| `SMPP_SYSTEM_TYPE` | SMPP system type | `TR` |
| `SMPP_BIND_MODE` | Bind mode | `transceiver` |
| `SMPP_INTERFACE_VERSION` | SMPP interface version | `0x34` |
| `SMPP_ORIGINATOR_TON` | Source TON | `5` |
| `SMPP_ORIGINATOR_NPI` | Source NPI | `0` |
| `SMPP_DESTINATION_TON` | Destination TON | `2` |
| `SMPP_DESTINATION_NPI` | Destination NPI | `1` |
| `SMPP_CONNECT_TIMEOUT` | Validated connection-time compatibility value | `10`; the current vendor socket path cannot enforce a distinct TCP connect timeout |
| `SMPP_READ_TIMEOUT` | Read timeout | `10000` |
| `SMPP_WRITE_TIMEOUT` | Write timeout | `10000` |
| `SMPP_MAX_SESSIONS` | Confirmed session limit | `1` |
| `YAS_OPERATIONAL_DISPATCH_ENABLED` | Activates the operational YAS outbox bridge | `false` until approved configuration and acceptance |
| `YAS_SMPP_RUNTIME_ENABLED` | Runtime-foundation enable flag | `false`; no persistent runtime process command is implemented |
| `YAS_SMPP_LEASE_TTL_MS` | Runtime lease lifetime | `<APPROVED_VALUE>` |
| `YAS_SMPP_HEARTBEAT_INTERVAL_MS` | Lease heartbeat interval | `<APPROVED_VALUE>` |
| `YAS_SMPP_POLLING_INTERVAL_MS` | Submission polling interval | `<APPROVED_VALUE>` |
| `YAS_SMPP_KEEPALIVE_INTERVAL_MS` | Enquire-link planning interval | `<YAS_APPROVED_VALUE>` |
| `YAS_SMPP_KEEPALIVE_RESPONSE_TIMEOUT_MS` | Enquire-link response limit | `<YAS_APPROVED_VALUE>` |
| `YAS_SMPP_KEEPALIVE_FAILURE_THRESHOLD` | Keepalive failure threshold | `<APPROVED_VALUE>` |
| `YAS_SMPP_RECONNECT_INITIAL_DELAY_MS` | Runtime reconnect planning input | `<APPROVED_VALUE>` |
| `YAS_SMPP_RECONNECT_MAXIMUM_DELAY_MS` | Runtime reconnect planning limit | `<APPROVED_VALUE>` |
| `YAS_SMPP_GRACEFUL_SHUTDOWN_TIMEOUT_MS` | Runtime shutdown planning limit | `<APPROVED_VALUE>` |
| `YAS_SMPP_INBOUND_RETENTION_DAYS` | Runtime inbound-retention setting | `<APPROVED_VALUE>` |

The runtime timing keys must be complete whenever runtime configuration is resolved, even while disabled. They are planning/configuration authorities, not evidence of an installed long-lived process.

There is no implemented `SMPP_SOURCE_ADDRESS` environment key. Every API request must supply an active `sender_id` assigned to the authenticated application. Sender approval occurs with YAS outside the gateway in this release.

There is no implemented SMPP TLS configuration key in `config/smpp.php`. Do not claim SMPP TLS until YAS transport requirements and a matching implementation are approved. Public API and tenant webhook URLs still require HTTPS.

`SMPP_PASSWORD` is the implemented input. Production operations should inject it through approved secret management into the environment; the repository does not define a separate YAS password-reference key. Never print it in command output or logs.

## Illustrative environment inventory

```dotenv
SMPP_CONNECTION=yas
SMPP_CONNECTION_YAS_NAME=yas
SMPP_HOST=<YAS_HOST>
SMPP_BACKUP_HOST=
SMPP_PORT=<YAS_PORT>
SMPP_SYSTEM_ID=<YAS_SYSTEM_ID>
SMPP_PASSWORD=<YAS_PASSWORD>
SMPP_SYSTEM_TYPE=TR
SMPP_BIND_MODE=transceiver
SMPP_INTERFACE_VERSION=0x34
SMPP_ORIGINATOR_TON=5
SMPP_ORIGINATOR_NPI=0
SMPP_DESTINATION_TON=2
SMPP_DESTINATION_NPI=1
SMPP_CONNECT_TIMEOUT=10
SMPP_READ_TIMEOUT=10000
SMPP_WRITE_TIMEOUT=10000
SMPP_MAX_SESSIONS=1
YAS_OPERATIONAL_DISPATCH_ENABLED=false
YAS_SMPP_RUNTIME_ENABLED=false
```

The example does not authorize or supply YAS values. Keep both enable flags false until the complete external and operational checklist is approved.

## YAS pre-acceptance information

| Item | Repository evidence | Acceptance state |
| --- | --- | --- |
| SMPP endpoint and port | Keys exist; live values absent | To be confirmed with YAS |
| Bind credentials | System ID/password keys exist; live values absent | To be confirmed with YAS |
| Supported bind mode | Gateway requires transceiver | YAS support to be confirmed |
| Permitted source addresses/sender IDs | API supports sender ID; YAS allowlist absent | To be confirmed with YAS |
| Source TON/NPI | Gateway requires `5/0` | YAS agreement to be confirmed |
| Destination TON/NPI | Gateway requires `2/1` | YAS agreement to be confirmed |
| Destination number format | Public API uses E.164 | YAS format to be confirmed |
| Supported data coding | Gateway preserves protocol coding and conservatively parses supported textual receipts | YAS submitted-message and DLR coding to be confirmed |
| Maximum message size/multipart | Public API accepts its frozen limit; no RC1 multipart contract is approved | To be confirmed with YAS; multipart acceptance is pending |
| `submit_sm_resp` expectations | Gateway records acknowledgement and optional provider reference | Exact YAS statuses to be confirmed |
| Provider message ID format | Correlation supports a bounded provider reference | To be confirmed with YAS |
| Delivery receipt enablement | Diagnostic supports `--request-dlr` | Account enablement to be confirmed |
| `registered_delivery` requirement | Gateway can request final receipts | Required YAS byte/policy to be confirmed |
| Textual/TLV DLR format | Gateway validates supported SMPP receipt evidence | Exact YAS fields, termination, duplicates, and coding to be confirmed |
| DLR statuses | Gateway recognizes `ENROUTE`, `ACCEPTD`, `DELIVRD`, `EXPIRED`, `DELETED`, `UNDELIV`, `REJECTD`, `UNKNOWN` | YAS emitted subset to be confirmed |
| DLR timing | No YAS service-level evidence in repository | To be confirmed with YAS |
| Throughput limit | No YAS TPS value in repository | To be confirmed with YAS |
| Bind/IP whitelisting | No live allowlist in repository | To be confirmed with YAS |
| Firewall requirements | No external firewall evidence in repository | To be confirmed with YAS and infrastructure owner |
| SMPP TLS requirement | No SMPP TLS switch is implemented | To be confirmed with YAS; implementation review required if mandatory |
| Test MSISDNs | None documented | To be confirmed with YAS |
| Maintenance/support contact | None documented | To be confirmed with YAS |
| Acceptance window | None documented | To be confirmed with YAS |
| Escalation path | None documented | To be confirmed with YAS and project owner |

## Pre-live checks

1. Obtain written confirmation for every table item above.
2. Confirm the test source address, MSISDN, text, and expected DLR outcome are approved.
3. Confirm the gateway egress IP and YAS firewall state.
4. Configure secrets outside source control.
5. Keep `YAS_OPERATIONAL_DISPATCH_ENABLED=false` while running configuration and bind diagnostics.
6. Confirm no competing diagnostic or operational session uses the same System ID; `SMPP_MAX_SESSIONS=1` is authoritative.
7. Record the acceptance window and both escalation contacts.

## Existing diagnostic procedure

Validate only the bind:

```console
php artisan gateway:smpp:bind-test yas
```

After bind approval, submit one authorized live test and request a DLR:

```console
php artisan gateway:sms:send-test yas --to=<TEST_MSISDN> --from=<APPROVED_SENDER> --message=<APPROVED_TEST_TEXT> --request-dlr
```

The command is interactive unless `--force` is provided. Preserve the sanitized result and provider reference. Do not expose the password, message content, or full test number in general-purpose logs or tickets.

The repository has no production command for injecting a raw PDU and this guide does not define one. Local fixture/simulator tests may use test-only mechanisms; live DLRs must arrive through the existing approved inbound transport path.

## End-to-end live acceptance

Follow [ACCEPTANCE_CHECKLIST.md](ACCEPTANCE_CHECKLIST.md): submit through the public API, observe queued/submitted status, capture authorized internal provider acknowledgement, receive the YAS DLR, verify normalized projection, and verify the optional terminal webhook signature. Repeat with YAS-approved failure and duplicate scenarios only when YAS can safely produce them.

Local fixture success is automated/internal evidence, not YAS acceptance. Mark YAS acceptance complete only with a dated representative sign-off or equivalent acceptance record.

## Tenant webhook receiver

Receiver authentication rules and language-neutral HMAC pseudocode are in [RELEASE_CANDIDATE.md](RELEASE_CANDIDATE.md#webhook-receiver-guide). The receiver must retain the prior secret for the 24-hour overlap, enforce the five-minute timestamp window, compare signatures in constant time, and return a prompt 2xx. RC1 sends one attempt only.