Ports
The sixteen interfaces the core calls on a connector — which are required, which a capability binds, which are optional, the value objects that cross them, and the rules every implementation shares.
A port is an interface under Subscriby\Connector\Contracts\Ports. The core reaches a connector only through ports, and every method takes and returns SDK value objects from Subscriby\Connector\Data: an InstallationRef and the installation's CredentialBag say which installation acts and with what, a SpaceRef names a gated place, an IdentityRef a person's account, a GrantRef an access record. Eloquent models never cross in either direction.
The Connector class binds each port by its interface name through the ConnectorRegistrar; the registry checks the bindings against the manifest's capabilities at boot.
The sixteen ports
| Port | Bound | In one sentence |
|---|---|---|
InstallationLifecycle | always | Connecting, verifying, describing and disconnecting an installation on the platform. |
IdentityResolver | always | Who an inbound event is from, and what the platform knows about an account. |
InboundGateway | always | Turning what the platform sends into authenticated, deduplicated events. |
FailureClassifier | always | Reading why the platform refused a call, in the core's seven kinds. |
TextRenderer | always | Turning the canonical HTML into what the platform accepts. |
SettingsSchema | always (usually from the manifest) | The install and settings forms as data. |
UiSlots | always | The connector's contributions to the core's UI slots, even when there are none. |
Messenger | messaging, broadcasts | Sending, editing and deleting the core's messages, and sending files. |
AccessController | access_control, early_admission_hold | Granting, revoking, admitting, announcing and reconciling access to places. |
SupportRelay | support_relay | Carrying a support conversation to the creator on the platform and back. |
PortalLoginMethod | portal_login | Signing a member into the portal through the platform. |
RegistersCreators | creator_registration | Where a creator account can be started from inside the platform. |
ManagementSurface | management_surface | The creator's in-chat admin surface over the core's command catalogue. |
ProvidesPaymentMethods | native_payments (official only) | Payment methods that exist only because of the platform. |
RecoverySupport | any recovery_* | What the Disaster Recovery Program needs a connector to witness and do. |
SpaceCatalog | optional, no capability | How a creator picks a place to gate, and whether the installation controls it. |
Rules every port shares
- Refs in, results out. A port never receives a model, a request from the dashboard or a database row; it receives refs (
InstallationRef,IdentityRef,SpaceRef,GrantRef,ProjectRef,CreatorRef,MemberRef) that carry the ids and external ids it needs, and returns result objects (GrantResult,DeliveryResult,InstallationHealth, …) rather than throwing on a platform refusal. - Credentials arrive per call. The
CredentialBagis decrypted for the duration of one call and handed in beside theInstallationRef. A port never stores it, logs it or reads the core's table. - Refusals are classified, not thrown. Every send, grant and probe reports a
DeliveryFailure(kind, detail, retry-after, platform code) built by yourFailureClassifier; the core decides from the kind whether to retry, wait, alert the creator or give up. An exception is for a programming error, not for a platform that said no. - Idempotent by design. The core retries.
grant()called twice yields one grant,revoke()of what the platform already lost reports revoked,record()on the Core API rewrites rather than duplicates, and a replayed inbound event is dropped by the core before it reaches you, but your own side effects must tolerate a second call all the same. - Unsupported facets throw once. A method the manifest denies (a recovery facet, early admission on a kind that has none) throws
Subscriby\Connector\Exceptions\UnsupportedByConnector. The core never calls a denied facet; the throw is there for the day it is called by mistake. - Nothing from the application's namespace. A port reads the core through
Subscriby\Connector\Core\*(Core API) and its own repositories, never throughApp\*. Subscriby's suite fails a package that does.
Value objects you will meet on every page
| Object | Carries |
|---|---|
InstallationRef | id, connector, scope (platform or project), projectId, externalId (the bot or app id), storageRef (your own row), handle. |
CredentialBag | get(key), has(key), toArray(): the secrets the install form's secret fields and your complete() stored. |
IdentityRef | id, connector, externalId, storageRef. |
SpaceRef | id, connector, externalId, kind, storageRef, parentExternalId (a role's guild, a topic's group). |
GrantRef | id, mode (GrantMode), reference (what you issued). |
DeliveryFailure | kind (DeliveryFailureKind), detail, retryAfterSeconds, code. |
DeliveryResult | delivered, externalMessageId, failure. |
Where each port is called from
Every page below says which core surface drives the port today: a dashboard action, a scheduled job, a REST endpoint, the conformance kit. A method the core does not yet call is marked as such, so you know what the kit exercises and what only a future core release will.
How is this guide?
listing
What the marketplace shows — category, tagline, overview, screenshots, links, dates — plus the words the marketing site borrows and the button the member portal shows.
InstallationLifecycle
Connecting, verifying, describing and disconnecting an installation on the platform — the eight methods, the value objects they exchange, and how the Connect dialog, the Verify button and the deep links drive them.