Social

Package social is posting to every social account you own, now or on a schedule.

Specification

/v1/social is posting to every social account an org owns, now or on a schedule. Two entities: an Account is a connected channel (X, Facebook, Instagram, LinkedIn, TikTok, YouTube, Threads) and a Post is content published or scheduled to one — scheduling is not a third entity, it is a Post with a future scheduleAt. It is implemented in hanzoai/cloud at apps/social, the in-process fold of the standalone social stack, and its defining honesty is that the publish edge fails closed: it reports exactly which provider credentials are missing and never fakes success.

Motivation

Social publishing had three homes: the standalone pods, a second path in the content app reaching the same upstream over HTTP, and a third scheduled-post store in marketing with no publisher wired at all. This fold — which owns the accounts, the scheduler and the publish edge — is the one (apps/social/social.go). Ground truth for the fail-closed default: no deployment carries the per-provider OAuth-app credentials the live orchestrator needs and no account access tokens exist, so there was no publishing capability to preserve, only one to enable (apps/social/publish.go).

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

The store

One SQLite file through the fleet's one opener (sqlpool.Open("social", dir), apps/social/store.go:34) holds every org's accounts and posts; tenant isolation is the org column, enforced on every query. Post lifecycle is four user-settable states (draft, scheduled, published, failed) plus a transient publishing claim state that is NEVER user-settable: ClaimForPublish is the guard that stops two publishers double-posting the same row, and stuck claims are recovered at mount.

The address

Thirteen operations under /v1/social, all of them typed ops (apps/social/social.go:176-190, models in apps/social/typed.go): the account collection and item, the post collection and item, POST /v1/social/posts/{id}/publish, a per-org summary and a providers read reporting publish-readiness per network with the exact credential names still missing. Nothing on this surface is wire-bound — every operation answers a value its own handler assembled — so the debt this section recorded is paid rather than deferred, and the ledger that would hold an exception is empty with the count pinned at thirteen (apps/social/typed_wire_test.go:122, :185).

What is published is the store's own row: socialAccount and socialPost are the types the store scans into rather than a view copied beside them, because a second copy is a second thing to keep true and its drift is silent. What typing adds is the REQUEST half a row cannot state — a create accepts no id, createdAt or updatedAt, since the server mints all three, and an account's provider token is neither accepted nor returned here at all (apps/social/typed.go:113-122). The names carry the product because a Go type name becomes a schema name in the one fleet document, where two apps may not mean different things by one name (openapi/weave.go:112): the request bodies are socialAccountBody and socialPostBody, never a bare Account or Post.

Where a handler assembled a map, field order is load-bearing: encoding/json writes a map's keys sorted and a struct in declaration order, so socialSummary declares its four alphabetically and the summary's bytes did not move (TestSummaryBytesDidNotMove, apps/social/typed_wire_test.go:283).

Publishing

One path pushes a post out (publish.go): on explicit publish, on create when scheduled for now-or-earlier, and on the scheduler tick when a scheduled time arrives. A post fans out to its channel's connected accounts through the Publisher edge, selected once at mount. The default Publisher MUST fail closed — a publish with missing provider credentials answers 503 naming what is absent, and MUST NOT mark the post published. The provider vocabulary is one ordered list from which validation, ordering and credential-checking all derive.

Tenancy

The org is principal.Org — minted from the validated bearer owner (HIP-0026) — never a client-supplied header, and it is the mandatory predicate on every store query.

Money, events, observability, stage

It is free — the surface declares cloud.Free (plugin/social/main.go). It publishes nothing on the bus; the scheduler delivers posts to networks, not events to webhooks. It emits nothing beyond the request span every route gets. The stage is beta: a vertical application whose per-account OAuth connect flow and native provider push are the declared remaining gap.

Upstream

It derives from the standalone hanzoai/social stack — its own lineage, not a third-party fork. What survives in HEAD is the model (integration → Account, post-now-or-schedule → Post), the provider vocabulary, and the orchestrator's exact credential names; the pods' HTTP surface is replaced by this in-process fold. No third-party OSS is embedded; the networks are reached as remote APIs.

Rationale

The alternative to a fail-closed publisher is a stub that returns success, which is the worst possible product: a customer schedules a campaign and nothing is delivered anywhere, silently. Reporting the missing credentials by name makes the 503 an installation instruction. The claim state exists because the same post is reachable from three triggers; without a claim, the scheduler and an explicit publish racing is a double post on a customer's public channel.

Security Considerations

The stored account rows will carry per-account OAuth tokens once the connect flow lands, which makes the org predicate the boundary between one tenant's audience and another's: the wrong implementation posts one org's content through another org's accounts — public, attributable damage. The other wrong implementation is accepting publishing from a request, which lets a caller wedge or replay the claim guard; the state vocabulary therefore excludes it from every write path.

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/social/posts, operation get_social_posts:

hanzo social posts list

import { Configuration, SocialApi } from 'hanzoai';

const api = new SocialApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getSocialPosts();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SocialApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SocialApi(client).get_social_posts()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.SocialAPI.GetSocialPosts(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, social_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = social_api::get_social_posts(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SocialApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new SocialApi(client).getSocialPosts();

curl https://api.hanzo.ai/v1/social/posts \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_social_accounts"
         }
       }
     }'

Answers 200 with object — ok.

Endpoints

All Hanzo APIs · Interactive reference