Integrate the Social SDK

A mock-first integration path for authorized account connections, durable publishing, per-target outcomes, and verified webhook processing.

This guide turns the Social SDK’s core contracts into an application integration. Keep account ownership in your application, use a real provider callback exchange, and treat each delivery outcome independently.

Build in this order

1. Start with mockBackend and MemoryIdempotencyStore from @opencoredev/social-sdk/testing. Exercise success, partial, processing, unknown, and failed outcomes with mock scenarios.
2. Configure an AuthorizationPolicy in createSocial({ authorization }) that checks your server-owned grants, and pass { authorization: { tenantId, principalId } } from the authenticated session to publish and facade calls. The call option alone is not a grant; without a configured policy the client performs no access check. See authorization.
3. Add ConnectionManager from @opencoredev/social-sdk/server. Call begin with the authenticated tenant and principal and an exact HTTPS callback allowlist, discover in the callback handler, and select with the accounts the user picked. Only select writes grants. Do not call a provider’s complete method directly; the manager checks the principal, state, redirect, expiry, and one-use code claim around it. See connect accounts.
4. Use the provider factories from @opencoredev/social-sdk/server, such as xOAuth or youtubeOAuth, or implement ConnectionProvider with the provider’s documented callback and token APIs. The SDK does not pretend to complete OAuth for a provider it cannot call.
5. Verify webhook signatures over the untouched request bytes. For managed backends, decode with decodeWebhook({ provider: "zernio" | "post-for-me", ... }). For direct platform webhooks, decode with decodePlatformWebhook({ platform, ... }). Resolve account IDs to tenant IDs and call acceptWebhook into an application-owned inbox. Unmapped events are quarantined; duplicates are acknowledged without reprocessing. See process webhooks.
6. Replace in-memory stores with durable transactions for connection attempts, grants, credentials, idempotency, and inbox state before production.

Recipes

The repository skill includes TypeScript shapes in references/mock-server.ts, references/connection-callback.ts, references/render-outcomes.ts, references/webhook-handler.ts, and references/integration.test.ts. They are repository examples, not package exports.

Review checklist

• Provider secrets stay on the server.
• createSocial has an AuthorizationPolicy, and every call passes the authenticated tenant and principal.
• Every publish result is rendered per target, including unknown and not-submitted.
• Callback state, redirect URI, tenant, principal, expiry, and replay are checked by ConnectionManager.
• Webhooks are verified before parsing and accepted into a deduplicated inbox before processing.
• Tests cover unauthorized selection, callback replay, duplicate events, partial results, and quarantine.