ad2app-lib 1.37.0 → 1.39.0

package/dist/analytics/index.d.ts

@@ -32,6 +32,7 @@ export declare const EVENTS: {
     readonly PROFILE_COMPLETED: "profile_completed";
     readonly LOGGED_IN: "logged_in";
     readonly SOCIAL_ACCOUNT_CONNECTED: "social_account_connected";
+    readonly SOCIAL_SIGN_IN_FAILED: "social_sign_in_failed";
     readonly COMPOSE_STARTED: "compose_started";
     readonly COMPOSE_STEP_VIEWED: "compose_step_viewed";
     readonly COMPOSE_BLOCKED: "compose_blocked";
@@ -44,6 +45,9 @@ export declare const EVENTS: {
     readonly CHECKOUT_STARTED: "checkout_started";
     readonly SUBSCRIPTION_STARTED: "subscription_started";
     readonly SUBSCRIPTION_CANCELED: "subscription_canceled";
+    readonly BILLING_PORTAL_OPENED: "billing_portal_opened";
+    readonly SUBSCRIPTION_REACTIVATED: "subscription_reactivated";
+    readonly CHECKOUT_CONFIRMATION_TIMED_OUT: "checkout_confirmation_timed_out";
     readonly PAYWALL_SHOWN: "paywall_shown";
     readonly PAYWALL_DISMISSED: "paywall_dismissed";
     readonly ACCESS_DENIED: "access_denied";
@@ -75,6 +79,12 @@ export declare const EVENTS: {
     readonly POST_RESCHEDULED: "post_rescheduled";
     readonly ACCOUNT_DISCONNECTED: "account_disconnected";
     readonly NOTIFICATION_PREFERENCES_UPDATED: "notification_preferences_updated";
+    readonly THEME_CHANGED: "theme_changed";
+    readonly FEEDBACK_SUBMITTED: "feedback_submitted";
+    readonly ACCOUNT_DELETED: "account_deleted";
+    readonly LANGUAGE_CHANGED: "language_changed";
+    readonly COMMENT_GUARD_MODE_CHANGED: "comment_guard_mode_changed";
+    readonly AI_TOOLS_REVOKE_REQUESTED: "ai_tools_revoke_requested";
     readonly NATIVE_SESSION_LAUNCHED: "native_session_launched";
     readonly NATIVE_SESSION_RENEWED: "native_session_renewed";
     readonly NATIVE_SESSION_ENDED: "native_session_ended";
@@ -165,7 +175,7 @@ export type ComposeStep = 'platforms' | 'content' | 'details' | 'review';
  * content, so neither may ride the event: only the class does. Same contract as
  * PublishFailureReason. Do NOT rename after shipping — wire values.
  */
-export type ComposeBlockReason = 'empty' | 'missing_fields' | 'over_limit' | 'media' | 'channel_blocked' | 'poll';
+export type ComposeBlockReason = 'empty' | 'missing_fields' | 'over_limit' | 'media' | 'channel_blocked' | 'poll' | 'unconnected_platform';
 /**
  * Why a connect attempt ended without a connected account (spec 155 US3).
  *
@@ -196,9 +206,11 @@ export type ComposeBlockReason = 'empty' | 'missing_fields' | 'over_limit' | 'me
 export type OnboardingCompletedAt = 'connect' | 'install' | 'schedule';
 /** The finish lines, in the order the flow can reach them. */
 export declare const ONBOARDING_COMPLETED_AT: readonly ["connect", "install", "schedule"];
-export type ConnectBlockReason = 'paywall' | 'canceled' | 'failed' | 'returned_without_account' | 'personal_profile';
+export type ConnectBlockReason = 'paywall' | 'canceled' | 'failed' | 'returned_without_account' | 'personal_profile' | 'api_failed' | 'timeout' | 'exception';
 /** The reason set, in the order the spec lists it. Iterable for contract tests and dashboards. */
-export declare const CONNECT_BLOCK_REASONS: readonly ["paywall", "canceled", "failed", "returned_without_account", "personal_profile"];
+export declare const CONNECT_BLOCK_REASONS: readonly ["paywall", "canceled", "failed", "returned_without_account", "personal_profile", "api_failed", "timeout", "exception"];
+export type SignInFailureReason = 'canceled' | 'missing_code' | 'invalid_provider' | 'no_email' | 'api_failed' | 'exception';
+export declare const SIGN_IN_FAILURE_REASONS: readonly ["canceled", "missing_code", "invalid_provider", "no_email", "api_failed", "exception"];
 export type PublishFailureReason = 'auth' | 'rate_limit' | 'media' | 'content' | 'network' | 'platform' | 'unknown';
 /** Property shape per event. Keeps emitters honest across repos. */
 export interface EventProperties {
@@ -261,6 +273,10 @@ export interface EventProperties {
         account_count?: number;
         connection_ordinal?: number;
     };
+    [EVENTS.SOCIAL_SIGN_IN_FAILED]: {
+        platform?: string;
+        reason: SignInFailureReason;
+    };
     [EVENTS.COMPOSE_STARTED]: {
         source?: 'wizard' | 'quick';
     };
@@ -324,6 +340,15 @@ export interface EventProperties {
         plan: string;
         reason?: string;
     };
+    [EVENTS.BILLING_PORTAL_OPENED]: {
+        plan: string;
+    };
+    [EVENTS.SUBSCRIPTION_REACTIVATED]: {
+        plan: string;
+    };
+    [EVENTS.CHECKOUT_CONFIRMATION_TIMED_OUT]: {
+        had_session_id: boolean;
+    };
     [EVENTS.PAYWALL_SHOWN]: {
         surface: 'upgrade_modal' | 'pricing_page';
         trigger: 'user_click' | 'limit_reached' | 'connect_wall';
@@ -475,6 +500,22 @@ export interface EventProperties {
         enabled?: boolean;
         success: boolean;
     };
+    [EVENTS.THEME_CHANGED]: {
+        mode: 'light' | 'dark';
+    };
+    [EVENTS.FEEDBACK_SUBMITTED]: {
+        has_screenshot: boolean;
+    };
+    [EVENTS.ACCOUNT_DELETED]: {
+        tier: string;
+    };
+    [EVENTS.LANGUAGE_CHANGED]: {
+        language: 'en' | 'pl';
+    };
+    [EVENTS.COMMENT_GUARD_MODE_CHANGED]: {
+        mode: 'off' | 'flag-only' | 'auto-ignore';
+    };
+    [EVENTS.AI_TOOLS_REVOKE_REQUESTED]: Record<string, never>;
     [EVENTS.NATIVE_SESSION_LAUNCHED]: {
         outcome: 'restored' | 'none' | 'degraded';
     };

package/dist/analytics/index.js

@@ -10,7 +10,7 @@
  * Do NOT rename events after they ship — historical data does not migrate.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LAUNCH_CONTEXT_PROPS = exports.PERSON_PROPS = exports.CONNECT_BLOCK_REASONS = exports.ONBOARDING_COMPLETED_AT = exports.EMAIL_PROPS = exports.EVENTS = void 0;
+exports.LAUNCH_CONTEXT_PROPS = exports.PERSON_PROPS = exports.SIGN_IN_FAILURE_REASONS = exports.CONNECT_BLOCK_REASONS = exports.ONBOARDING_COMPLETED_AT = exports.EMAIL_PROPS = exports.EVENTS = void 0;
 /** Canonical PostHog event names. */
 exports.EVENTS = {
     // Acquisition (landing)
@@ -42,6 +42,12 @@ exports.EVENTS = {
     PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
     LOGGED_IN: 'logged_in',
     SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
+    // 164 G007: OAuthCallbackPage's sign-in branch (state !== 'web-connect')
+    // had zero tracking on any of its 5 failure outcomes -- LOGGED_IN only
+    // ever fires on success (PostHogIdentify.tsx, centrally, off the redux
+    // authed state), so failures need their own event rather than an
+    // overloaded success/failure LOGGED_IN.
+    SOCIAL_SIGN_IN_FAILED: 'social_sign_in_failed',
     COMPOSE_STARTED: 'compose_started',
     // AD2-1371: the composer was a black box between COMPOSE_STARTED and
     // POST_SCHEDULED. Measured 2026-08-28: of seven users who connected an
@@ -61,6 +67,17 @@ exports.EVENTS = {
     CHECKOUT_STARTED: 'checkout_started',
     SUBSCRIPTION_STARTED: 'subscription_started',
     SUBSCRIPTION_CANCELED: 'subscription_canceled',
+    // 164 G009 (SubscriptionSection had zero tracking on either action): client
+    // intent only — CANCEL_INITIATED above is already backend/webhook-owned
+    // (fires off the real `cancel_at_period_end` transition), so cancel itself
+    // is deliberately NOT duplicated here.
+    BILLING_PORTAL_OPENED: 'billing_portal_opened',
+    SUBSCRIPTION_REACTIVATED: 'subscription_reactivated',
+    // 164 (ComposePage -> PaymentProcessingPage): the client gave up polling for
+    // Stripe/webhook confirmation. Distinct from the backend-owned PAYMENT_FAILED
+    // (a real decline) -- this only means "we could not confirm in time", which
+    // may still resolve moments later.
+    CHECKOUT_CONFIRMATION_TIMED_OUT: 'checkout_confirmation_timed_out',
     // Measurement baseline (080) — paywall / onboarding / exit-intent (frontend-owned)
     PAYWALL_SHOWN: 'paywall_shown', // any monetization surface is shown (upgrade modal / pricing page)
     PAYWALL_DISMISSED: 'paywall_dismissed', // closed without converting
@@ -110,6 +127,19 @@ exports.EVENTS = {
     ACCOUNT_DISCONNECTED: 'account_disconnected',
     // Settings.
     NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
+    // 164 G009: SettingsPage had `track`/`EVENTS` imported but never called --
+    // theme, feedback, and account-deletion all fired nothing. NOTIFICATION_PREFERENCES_UPDATED
+    // above already covers the marketing-emails toggle (its declared `{preference, enabled,
+    // success}` shape fits exactly; reused rather than adding a parallel event).
+    THEME_CHANGED: 'theme_changed',
+    FEEDBACK_SUBMITTED: 'feedback_submitted',
+    ACCOUNT_DELETED: 'account_deleted',
+    // Shared LanguageSwitcher (SignIn/SignUp/Settings) had the same zero-tracking gap.
+    LANGUAGE_CHANGED: 'language_changed',
+    // Behind SHOW_COMMENT_GUARD_SECTION / SHOW_AI_TOOLS_SECTION (both default OFF) —
+    // no real user can reach either today, but fixed for completeness/G009.
+    COMMENT_GUARD_MODE_CHANGED: 'comment_guard_mode_changed',
+    AI_TOOLS_REVOKE_REQUESTED: 'ai_tools_revoke_requested',
     // Native session lifecycle (159) — the iOS wrapper's Keychain-backed session,
     // reported so "does it survive" is a query instead of an inference from login
     // counts. Native only; the web session's posture is unchanged (contract Rule 5).
@@ -151,6 +181,17 @@ exports.CONNECT_BLOCK_REASONS = [
     'failed',
     'returned_without_account',
     'personal_profile',
+    'api_failed',
+    'timeout',
+    'exception',
+];
+exports.SIGN_IN_FAILURE_REASONS = [
+    'canceled',
+    'missing_code',
+    'invalid_provider',
+    'no_email',
+    'api_failed',
+    'exception',
 ];
 /** Canonical person property keys (set via identify / $set). */
 exports.PERSON_PROPS = {

package/dist/types/agent/I_AgentGrant.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+export declare const AGENT_SCOPES: readonly ["social:post", "social:read", "social:analytics", "social:accounts", "media:upload", "social:billing"];
+export type T_AgentScope = (typeof AGENT_SCOPES)[number];
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+export declare const isAgentScope: (value: string) => value is T_AgentScope;
+/** Why a grant stopped being usable. Recorded for audit; the row survives. */
+export type T_AgentGrantRevokedReason = 'creator' | 'admin' | 'credential_invalid' | 'superseded';
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+export declare class AgentGrantDTO {
+    /** The grant reference. Not a secret — useless without the client credential. */
+    id: string;
+    /** The acting client, e.g. "ad2app-mcp". */
+    clientId: string;
+    /** Granted capabilities. Never widened after issue; a wider grant is a new grant. */
+    scopes: T_AgentScope[];
+    createdAt: string;
+    /** Updated when an access token is issued, not on every request. */
+    lastUsedAt?: string | null;
+    revokedAt?: string | null;
+    revokedReason?: T_AgentGrantRevokedReason | null;
+    constructor(data: AgentGrantDTO);
+}
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+export declare class AgentAccessTokenRequestDTO {
+    /** The grant reference, and nothing else. */
+    grantId: string;
+    /**
+     * Optional narrowing: request FEWER scopes than the grant carries. Must be a
+     * subset — a request for more than was granted fails closed.
+     */
+    scopes?: T_AgentScope[];
+    constructor(data: AgentAccessTokenRequestDTO);
+}
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+export declare class AgentAccessTokenDTO {
+    accessToken: string;
+    /** Seconds. Also the documented worst-case revocation latency. */
+    expiresIn: number;
+    grantId: string;
+    scopes: T_AgentScope[];
+    constructor(data: AgentAccessTokenDTO);
+}
+/**
+ * The `act` claim: present ⇒ an agent is acting for the creator named by `sub`;
+ * absent ⇒ the creator is acting directly.
+ *
+ * This distinction is what the backend cannot currently make, and what lets
+ * agent-specific policy exist at all (spec FR-001).
+ */
+export interface I_AgentActorClaim {
+    client_id: string;
+    grant_id: string;
+}

package/dist/types/agent/I_AgentGrant.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentAccessTokenDTO = exports.AgentAccessTokenRequestDTO = exports.AgentGrantDTO = exports.isAgentScope = exports.AGENT_SCOPES = void 0;
+// ── Scopes ───────────────────────────────────────────────────────────────────
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+exports.AGENT_SCOPES = [
+    /** create, update, cancel and retry posts */
+    'social:post',
+    /** list posts, accounts and subscription status */
+    'social:read',
+    /** read account and post analytics */
+    'social:analytics',
+    /** connect and disconnect social accounts */
+    'social:accounts',
+    /** request upload authority for the creator's own media */
+    'media:upload',
+    /**
+     * Read subscription status and obtain an upgrade checkout URL.
+     *
+     * Deliberately separate from `social:read` (review L3): the checkout route is
+     * a POST that creates a Stripe session. It moves no money — the creator still
+     * pays on Stripe's own page — but a scope named "read" guarding it is the
+     * kind of mismatch that gets copied to somewhere it does matter.
+     */
+    'social:billing',
+];
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+const isAgentScope = (value) => exports.AGENT_SCOPES.includes(value);
+exports.isAgentScope = isAgentScope;
+// ── AgentGrantDTO ────────────────────────────────────────────────────────────
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+class AgentGrantDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.clientId = data.clientId;
+        this.scopes = data.scopes;
+        this.createdAt = data.createdAt;
+        this.lastUsedAt = data.lastUsedAt ?? null;
+        this.revokedAt = data.revokedAt ?? null;
+        this.revokedReason = data.revokedReason ?? null;
+    }
+}
+exports.AgentGrantDTO = AgentGrantDTO;
+// ── AgentAccessTokenRequestDTO ───────────────────────────────────────────────
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+class AgentAccessTokenRequestDTO {
+    constructor(data) {
+        this.grantId = data.grantId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AgentAccessTokenRequestDTO = AgentAccessTokenRequestDTO;
+// ── AgentAccessTokenDTO ──────────────────────────────────────────────────────
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+class AgentAccessTokenDTO {
+    constructor(data) {
+        this.accessToken = data.accessToken;
+        this.expiresIn = data.expiresIn;
+        this.grantId = data.grantId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AgentAccessTokenDTO = AgentAccessTokenDTO;

package/dist/types/agent/I_AgentMediaUpload.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+export declare class AgentUploadFileRequestDTO {
+    fileName: string;
+    /** Must be on the backend's MIME allowlist; checked per file, not per batch. */
+    fileType: string;
+    fileSize: number;
+    constructor(data: AgentUploadFileRequestDTO);
+}
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+export declare class AgentUploadBatchRequestDTO {
+    files: AgentUploadFileRequestDTO[];
+    constructor(data: AgentUploadBatchRequestDTO);
+}
+/** Why one file was refused. The rest of the batch is unaffected (FR-015). */
+export type T_AgentUploadRejectionReason = 'file_too_large' | 'unsupported_type' | 'invalid_name' | 'invalid_size';
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+export declare class AgentUploadTargetDTO {
+    fileName: string;
+    /**
+     * The opaque handle used when composing a post, as `media:<id>`.
+     * Neither the creator nor the model ever handles a raw storage location.
+     */
+    mediaRef: string;
+    /**
+     * Single-purpose, short-lived write authority for THIS file only.
+     * Not general storage access, not account access.
+     */
+    uploadUrl: string;
+    /** Seconds. */
+    expiresIn: number;
+    constructor(data: AgentUploadTargetDTO);
+}
+/** One refused file, named so the creator knows which (FR-015). */
+export declare class AgentUploadRejectionDTO {
+    fileName: string;
+    reason: T_AgentUploadRejectionReason;
+    /** Plain language, for the creator. No status codes, no internal rule names. */
+    message: string;
+    constructor(data: AgentUploadRejectionDTO);
+}
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+export declare class AgentUploadBatchResponseDTO {
+    targets: AgentUploadTargetDTO[];
+    rejections: AgentUploadRejectionDTO[];
+    /** Present when more entries remain; pass back to fetch the next page. */
+    nextCursor?: string | null;
+    constructor(data: AgentUploadBatchResponseDTO);
+}
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+export declare class AgentUploadConfirmationDTO {
+    mediaRef: string;
+    ready: boolean;
+    /** Set when not ready, in plain language the creator can act on. */
+    message?: string;
+    constructor(data: AgentUploadConfirmationDTO);
+}

package/dist/types/agent/I_AgentMediaUpload.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentUploadConfirmationDTO = exports.AgentUploadBatchResponseDTO = exports.AgentUploadRejectionDTO = exports.AgentUploadTargetDTO = exports.AgentUploadBatchRequestDTO = exports.AgentUploadFileRequestDTO = void 0;
+// ── Requests ─────────────────────────────────────────────────────────────────
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+class AgentUploadFileRequestDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.fileType = data.fileType;
+        this.fileSize = data.fileSize;
+    }
+}
+exports.AgentUploadFileRequestDTO = AgentUploadFileRequestDTO;
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+class AgentUploadBatchRequestDTO {
+    constructor(data) {
+        this.files = data.files;
+    }
+}
+exports.AgentUploadBatchRequestDTO = AgentUploadBatchRequestDTO;
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+class AgentUploadTargetDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.mediaRef = data.mediaRef;
+        this.uploadUrl = data.uploadUrl;
+        this.expiresIn = data.expiresIn;
+    }
+}
+exports.AgentUploadTargetDTO = AgentUploadTargetDTO;
+/** One refused file, named so the creator knows which (FR-015). */
+class AgentUploadRejectionDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.reason = data.reason;
+        this.message = data.message;
+    }
+}
+exports.AgentUploadRejectionDTO = AgentUploadRejectionDTO;
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+class AgentUploadBatchResponseDTO {
+    constructor(data) {
+        this.targets = data.targets;
+        this.rejections = data.rejections;
+        this.nextCursor = data.nextCursor ?? null;
+    }
+}
+exports.AgentUploadBatchResponseDTO = AgentUploadBatchResponseDTO;
+// ── Confirmation ─────────────────────────────────────────────────────────────
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+class AgentUploadConfirmationDTO {
+    constructor(data) {
+        this.mediaRef = data.mediaRef;
+        this.ready = data.ready;
+        this.message = data.message;
+    }
+}
+exports.AgentUploadConfirmationDTO = AgentUploadConfirmationDTO;

package/dist/types/agent/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+export * from './I_AgentGrant';
+export * from './I_AgentMediaUpload';

package/dist/types/agent/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./I_AgentGrant"), exports);
+__exportStar(require("./I_AgentMediaUpload"), exports);

package/dist/types/index.d.ts

@@ -35,4 +35,5 @@ export * from "./I_Collaboration";
 export * from "./I_Publish";
 export * from "./I_SM_Platform";
 export * from "./scheduling";
+export * from "./agent";
 export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -52,5 +52,7 @@ __exportStar(require("./I_Publish"), exports);
 __exportStar(require("./I_SM_Platform"), exports);
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 __exportStar(require("./scheduling"), exports);
+// ── Agent domain (delegated authority + direct media upload, spec 163) ───────
+__exportStar(require("./agent"), exports);
 // ── Access control ────────────────────────────────────────────────────────────
 __exportStar(require("./I_AccessDenial"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.37.0",
+  "version": "1.39.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/account-connect-blocked.test.ts

@@ -13,13 +13,19 @@ import { test } from 'node:test';
 import { CONNECT_BLOCK_REASONS, EVENTS } from './index';
 import type { ConnectBlockReason, EventProperties } from './index';
 
-test('the reason set is the five causes, as wire values', () => {
+test('the reason set is the eight causes, as wire values', () => {
+	// 164 G001: widened from five to eight — 'api_failed'/'timeout'/'exception'
+	// cover connectAccount() itself failing before any redirect ever happens
+	// (confirmed live 2026-09-07 as the one previously-untracked branch).
 	assert.deepEqual([...CONNECT_BLOCK_REASONS], [
 		'paywall',
 		'canceled',
 		'failed',
 		'returned_without_account',
 		'personal_profile',
+		'api_failed',
+		'timeout',
+		'exception',
 	]);
 });
 

package/src/analytics/index.test.ts

@@ -90,6 +90,8 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   // 'email' | 'google' union (compile-time, enforced by `tsc --noEmit`).
   [EVENTS.LOGGED_IN]: { method: "apple" },
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: { platform: "instagram" },
+  // 164 G007
+  [EVENTS.SOCIAL_SIGN_IN_FAILED]: { platform: "facebook", reason: "canceled" },
   [EVENTS.COMPOSE_STARTED]: {},
   [EVENTS.COMPOSE_STEP_VIEWED]: { step: "content" },
   [EVENTS.COMPOSE_BLOCKED]: { step: "content", reasons: ["missing_fields"], reason_count: 1 },
@@ -102,6 +104,11 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.CHECKOUT_STARTED]: { plan: "starter" },
   [EVENTS.SUBSCRIPTION_STARTED]: { plan: "starter" },
   [EVENTS.SUBSCRIPTION_CANCELED]: { plan: "starter" },
+  // 164 G011
+  [EVENTS.BILLING_PORTAL_OPENED]: { plan: "pro" },
+  [EVENTS.SUBSCRIPTION_REACTIVATED]: { plan: "pro" },
+  // 164 (PaymentProcessingPage)
+  [EVENTS.CHECKOUT_CONFIRMATION_TIMED_OUT]: { had_session_id: true },
   // 080 measurement baseline
   [EVENTS.PAYWALL_SHOWN]: { surface: "upgrade_modal", trigger: "user_click", hit_number: 1, app_locale: "en" },
   [EVENTS.PAYWALL_DISMISSED]: { surface: "upgrade_modal", trigger: "user_click", hit_number: 1, app_locale: "en" },
@@ -139,6 +146,14 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.NATIVE_SESSION_LAUNCHED]: { outcome: "restored" },
   [EVENTS.NATIVE_SESSION_RENEWED]: {},
   [EVENTS.NATIVE_SESSION_ENDED]: { cause: "rejected" },
+  // 164 G009 — SettingsPage had track/EVENTS imported but never called
+  [EVENTS.THEME_CHANGED]: { mode: "dark" },
+  [EVENTS.FEEDBACK_SUBMITTED]: { has_screenshot: false },
+  [EVENTS.ACCOUNT_DELETED]: { tier: "pro" },
+  [EVENTS.LANGUAGE_CHANGED]: { language: "pl" },
+  // 164 G012 — both behind default-OFF flags, fixed for completeness
+  [EVENTS.COMMENT_GUARD_MODE_CHANGED]: { mode: "flag-only" },
+  [EVENTS.AI_TOOLS_REVOKE_REQUESTED]: {},
 };
 
 test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {

package/src/analytics/index.ts

@@ -46,6 +46,12 @@ export const EVENTS = {
   PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
   LOGGED_IN: 'logged_in',
   SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
+  // 164 G007: OAuthCallbackPage's sign-in branch (state !== 'web-connect')
+  // had zero tracking on any of its 5 failure outcomes -- LOGGED_IN only
+  // ever fires on success (PostHogIdentify.tsx, centrally, off the redux
+  // authed state), so failures need their own event rather than an
+  // overloaded success/failure LOGGED_IN.
+  SOCIAL_SIGN_IN_FAILED: 'social_sign_in_failed',
   COMPOSE_STARTED: 'compose_started',
   // AD2-1371: the composer was a black box between COMPOSE_STARTED and
   // POST_SCHEDULED. Measured 2026-08-28: of seven users who connected an
@@ -66,6 +72,17 @@ export const EVENTS = {
   CHECKOUT_STARTED: 'checkout_started',
   SUBSCRIPTION_STARTED: 'subscription_started',
   SUBSCRIPTION_CANCELED: 'subscription_canceled',
+  // 164 G009 (SubscriptionSection had zero tracking on either action): client
+  // intent only — CANCEL_INITIATED above is already backend/webhook-owned
+  // (fires off the real `cancel_at_period_end` transition), so cancel itself
+  // is deliberately NOT duplicated here.
+  BILLING_PORTAL_OPENED: 'billing_portal_opened',
+  SUBSCRIPTION_REACTIVATED: 'subscription_reactivated',
+  // 164 (ComposePage -> PaymentProcessingPage): the client gave up polling for
+  // Stripe/webhook confirmation. Distinct from the backend-owned PAYMENT_FAILED
+  // (a real decline) -- this only means "we could not confirm in time", which
+  // may still resolve moments later.
+  CHECKOUT_CONFIRMATION_TIMED_OUT: 'checkout_confirmation_timed_out',
 
   // Measurement baseline (080) — paywall / onboarding / exit-intent (frontend-owned)
   PAYWALL_SHOWN: 'paywall_shown', // any monetization surface is shown (upgrade modal / pricing page)
@@ -121,6 +138,19 @@ export const EVENTS = {
 
   // Settings.
   NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
+  // 164 G009: SettingsPage had `track`/`EVENTS` imported but never called --
+  // theme, feedback, and account-deletion all fired nothing. NOTIFICATION_PREFERENCES_UPDATED
+  // above already covers the marketing-emails toggle (its declared `{preference, enabled,
+  // success}` shape fits exactly; reused rather than adding a parallel event).
+  THEME_CHANGED: 'theme_changed',
+  FEEDBACK_SUBMITTED: 'feedback_submitted',
+  ACCOUNT_DELETED: 'account_deleted',
+  // Shared LanguageSwitcher (SignIn/SignUp/Settings) had the same zero-tracking gap.
+  LANGUAGE_CHANGED: 'language_changed',
+  // Behind SHOW_COMMENT_GUARD_SECTION / SHOW_AI_TOOLS_SECTION (both default OFF) —
+  // no real user can reach either today, but fixed for completeness/G009.
+  COMMENT_GUARD_MODE_CHANGED: 'comment_guard_mode_changed',
+  AI_TOOLS_REVOKE_REQUESTED: 'ai_tools_revoke_requested',
 
   // Native session lifecycle (159) — the iOS wrapper's Keychain-backed session,
   // reported so "does it survive" is a query instead of an inference from login
@@ -242,7 +272,12 @@ export type ComposeBlockReason =
   | 'over_limit' // caption longer than a selected platform allows
   | 'media' // media rejected (format, size, duration, count)
   | 'channel_blocked' // the channel itself refused (e.g. a failed prerequisite read)
-  | 'poll'; // an incomplete or unpostable poll
+  | 'poll' // an incomplete or unpostable poll
+  // 164 G002: picking an unconnected platform at step 1 (Platforms) redirects
+  // straight to /accounts with zero analytics -- same "composer refused to
+  // let you proceed" shape as the publish-readiness reasons above, just one
+  // step earlier, so it reuses this event/reason set rather than a new event.
+  | 'unconnected_platform';
 
 /**
  * Why a connect attempt ended without a connected account (spec 155 US3).
@@ -285,7 +320,14 @@ export type ConnectBlockReason =
   | 'canceled'
   | 'failed'
   | 'returned_without_account'
-  | 'personal_profile';
+  | 'personal_profile'
+  // 164 G001: 'failed' above is the POST-redirect case (backend appends
+  // ?connect=failed once the provider has already handed control back).
+  // These three cover the connectAccount() API call itself never getting a
+  // redirect at all — confirmed live 2026-09-07 as the one untracked branch.
+  | 'api_failed'
+  | 'timeout'
+  | 'exception';
 
 /** The reason set, in the order the spec lists it. Iterable for contract tests and dashboards. */
 export const CONNECT_BLOCK_REASONS = [
@@ -294,8 +336,31 @@ export const CONNECT_BLOCK_REASONS = [
   'failed',
   'returned_without_account',
   'personal_profile',
+  'api_failed',
+  'timeout',
+  'exception',
 ] as const satisfies readonly ConnectBlockReason[];
 
+// 164 G007: covers OAuthCallbackPage's social sign-in branch (as opposed to
+// ConnectBlockReason, which covers its account-connect branch) -- distinct
+// enums because the two flows fail for different reasons.
+export type SignInFailureReason =
+  | 'canceled' // provider returned ?error= (user denied / backed out)
+  | 'missing_code' // callback landed with no ?code= at all
+  | 'invalid_provider' // :provider route param missing/unrecognized
+  | 'no_email' // provider granted no email (Facebook/TikTok phone-only) -- AD2-1252
+  | 'api_failed' // socialSignIn() resolved without an accessToken
+  | 'exception'; // socialSignIn() itself threw
+
+export const SIGN_IN_FAILURE_REASONS = [
+  'canceled',
+  'missing_code',
+  'invalid_provider',
+  'no_email',
+  'api_failed',
+  'exception',
+] as const satisfies readonly SignInFailureReason[];
+
 export type PublishFailureReason =
   | 'auth' // token expired / revoked / missing scope / permission denied
   | 'rate_limit' // provider throttled us (429 / quota)
@@ -352,6 +417,7 @@ export interface EventProperties {
     // 080: 1 = first-ever account, 2 = second… — the "second action" activation hook.
     connection_ordinal?: number;
   };
+  [EVENTS.SOCIAL_SIGN_IN_FAILED]: { platform?: string; reason: SignInFailureReason };
   [EVENTS.COMPOSE_STARTED]: { source?: 'wizard' | 'quick' };
   [EVENTS.COMPOSE_STEP_VIEWED]: { step: ComposeStep };
   [EVENTS.COMPOSE_BLOCKED]: {
@@ -419,6 +485,9 @@ export interface EventProperties {
     trigger_source?: TriggerSource; // 080
   };
   [EVENTS.SUBSCRIPTION_CANCELED]: { plan: string; reason?: string };
+  [EVENTS.BILLING_PORTAL_OPENED]: { plan: string };
+  [EVENTS.SUBSCRIPTION_REACTIVATED]: { plan: string };
+  [EVENTS.CHECKOUT_CONFIRMATION_TIMED_OUT]: { had_session_id: boolean };
 
   // ── Measurement baseline (080) — new event property shapes ──────────────────
   // Paywall surfaces (frontend). hit_number is the analytical truth (an event
@@ -511,6 +580,12 @@ export interface EventProperties {
 
   // Settings — which preference toggled and its new state.
   [EVENTS.NOTIFICATION_PREFERENCES_UPDATED]: { preference?: string; enabled?: boolean; success: boolean };
+  [EVENTS.THEME_CHANGED]: { mode: 'light' | 'dark' };
+  [EVENTS.FEEDBACK_SUBMITTED]: { has_screenshot: boolean };
+  [EVENTS.ACCOUNT_DELETED]: { tier: string };
+  [EVENTS.LANGUAGE_CHANGED]: { language: 'en' | 'pl' };
+  [EVENTS.COMMENT_GUARD_MODE_CHANGED]: { mode: 'off' | 'flag-only' | 'auto-ignore' };
+  [EVENTS.AI_TOOLS_REVOKE_REQUESTED]: Record<string, never>;
 
   // Native session lifecycle (159, contract session-reports.md). `outcome`
   // covers all three launch reports in one event (restored / none / degraded)

package/src/types/agent/I_AgentGrant.ts

@@ -0,0 +1,161 @@
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+
+// ── Scopes ───────────────────────────────────────────────────────────────────
+
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+export const AGENT_SCOPES = [
+  /** create, update, cancel and retry posts */
+  'social:post',
+  /** list posts, accounts and subscription status */
+  'social:read',
+  /** read account and post analytics */
+  'social:analytics',
+  /** connect and disconnect social accounts */
+  'social:accounts',
+  /** request upload authority for the creator's own media */
+  'media:upload',
+  /**
+   * Read subscription status and obtain an upgrade checkout URL.
+   *
+   * Deliberately separate from `social:read` (review L3): the checkout route is
+   * a POST that creates a Stripe session. It moves no money — the creator still
+   * pays on Stripe's own page — but a scope named "read" guarding it is the
+   * kind of mismatch that gets copied to somewhere it does matter.
+   */
+  'social:billing',
+] as const;
+
+export type T_AgentScope = (typeof AGENT_SCOPES)[number];
+
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+export const isAgentScope = (value: string): value is T_AgentScope =>
+  (AGENT_SCOPES as readonly string[]).includes(value);
+
+/** Why a grant stopped being usable. Recorded for audit; the row survives. */
+export type T_AgentGrantRevokedReason =
+  | 'creator'
+  | 'admin'
+  | 'credential_invalid'
+  | 'superseded';
+
+// ── AgentGrantDTO ────────────────────────────────────────────────────────────
+
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+export class AgentGrantDTO {
+  /** The grant reference. Not a secret — useless without the client credential. */
+  id: string;
+  /** The acting client, e.g. "ad2app-mcp". */
+  clientId: string;
+  /** Granted capabilities. Never widened after issue; a wider grant is a new grant. */
+  scopes: T_AgentScope[];
+  createdAt: string;
+  /** Updated when an access token is issued, not on every request. */
+  lastUsedAt?: string | null;
+  revokedAt?: string | null;
+  revokedReason?: T_AgentGrantRevokedReason | null;
+
+  constructor(data: AgentGrantDTO) {
+    this.id = data.id;
+    this.clientId = data.clientId;
+    this.scopes = data.scopes;
+    this.createdAt = data.createdAt;
+    this.lastUsedAt = data.lastUsedAt ?? null;
+    this.revokedAt = data.revokedAt ?? null;
+    this.revokedReason = data.revokedReason ?? null;
+  }
+}
+
+// ── AgentAccessTokenRequestDTO ───────────────────────────────────────────────
+
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+export class AgentAccessTokenRequestDTO {
+  /** The grant reference, and nothing else. */
+  grantId: string;
+  /**
+   * Optional narrowing: request FEWER scopes than the grant carries. Must be a
+   * subset — a request for more than was granted fails closed.
+   */
+  scopes?: T_AgentScope[];
+
+  constructor(data: AgentAccessTokenRequestDTO) {
+    this.grantId = data.grantId;
+    this.scopes = data.scopes;
+  }
+}
+
+// ── AgentAccessTokenDTO ──────────────────────────────────────────────────────
+
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+export class AgentAccessTokenDTO {
+  accessToken: string;
+  /** Seconds. Also the documented worst-case revocation latency. */
+  expiresIn: number;
+  grantId: string;
+  scopes: T_AgentScope[];
+
+  constructor(data: AgentAccessTokenDTO) {
+    this.accessToken = data.accessToken;
+    this.expiresIn = data.expiresIn;
+    this.grantId = data.grantId;
+    this.scopes = data.scopes;
+  }
+}
+
+// ── Token claim shape ────────────────────────────────────────────────────────
+
+/**
+ * The `act` claim: present ⇒ an agent is acting for the creator named by `sub`;
+ * absent ⇒ the creator is acting directly.
+ *
+ * This distinction is what the backend cannot currently make, and what lets
+ * agent-specific policy exist at all (spec FR-001).
+ */
+export interface I_AgentActorClaim {
+  client_id: string;
+  grant_id: string;
+}

package/src/types/agent/I_AgentMediaUpload.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+
+// ── Requests ─────────────────────────────────────────────────────────────────
+
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+export class AgentUploadFileRequestDTO {
+  fileName: string;
+  /** Must be on the backend's MIME allowlist; checked per file, not per batch. */
+  fileType: string;
+  fileSize: number;
+
+  constructor(data: AgentUploadFileRequestDTO) {
+    this.fileName = data.fileName;
+    this.fileType = data.fileType;
+    this.fileSize = data.fileSize;
+  }
+}
+
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+export class AgentUploadBatchRequestDTO {
+  files: AgentUploadFileRequestDTO[];
+
+  constructor(data: AgentUploadBatchRequestDTO) {
+    this.files = data.files;
+  }
+}
+
+// ── Responses ────────────────────────────────────────────────────────────────
+
+/** Why one file was refused. The rest of the batch is unaffected (FR-015). */
+export type T_AgentUploadRejectionReason =
+  | 'file_too_large'
+  | 'unsupported_type'
+  | 'invalid_name'
+  | 'invalid_size';
+
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+export class AgentUploadTargetDTO {
+  fileName: string;
+  /**
+   * The opaque handle used when composing a post, as `media:<id>`.
+   * Neither the creator nor the model ever handles a raw storage location.
+   */
+  mediaRef: string;
+  /**
+   * Single-purpose, short-lived write authority for THIS file only.
+   * Not general storage access, not account access.
+   */
+  uploadUrl: string;
+  /** Seconds. */
+  expiresIn: number;
+
+  constructor(data: AgentUploadTargetDTO) {
+    this.fileName = data.fileName;
+    this.mediaRef = data.mediaRef;
+    this.uploadUrl = data.uploadUrl;
+    this.expiresIn = data.expiresIn;
+  }
+}
+
+/** One refused file, named so the creator knows which (FR-015). */
+export class AgentUploadRejectionDTO {
+  fileName: string;
+  reason: T_AgentUploadRejectionReason;
+  /** Plain language, for the creator. No status codes, no internal rule names. */
+  message: string;
+
+  constructor(data: AgentUploadRejectionDTO) {
+    this.fileName = data.fileName;
+    this.reason = data.reason;
+    this.message = data.message;
+  }
+}
+
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+export class AgentUploadBatchResponseDTO {
+  targets: AgentUploadTargetDTO[];
+  rejections: AgentUploadRejectionDTO[];
+  /** Present when more entries remain; pass back to fetch the next page. */
+  nextCursor?: string | null;
+
+  constructor(data: AgentUploadBatchResponseDTO) {
+    this.targets = data.targets;
+    this.rejections = data.rejections;
+    this.nextCursor = data.nextCursor ?? null;
+  }
+}
+
+// ── Confirmation ─────────────────────────────────────────────────────────────
+
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+export class AgentUploadConfirmationDTO {
+  mediaRef: string;
+  ready: boolean;
+  /** Set when not ready, in plain language the creator can act on. */
+  message?: string;
+
+  constructor(data: AgentUploadConfirmationDTO) {
+    this.mediaRef = data.mediaRef;
+    this.ready = data.ready;
+    this.message = data.message;
+  }
+}

package/src/types/agent/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+
+export * from './I_AgentGrant';
+export * from './I_AgentMediaUpload';

package/src/types/index.ts

@@ -37,5 +37,8 @@ export * from "./I_SM_Platform";
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 export * from "./scheduling";
 
+// ── Agent domain (delegated authority + direct media upload, spec 163) ───────
+export * from "./agent";
+
 // ── Access control ────────────────────────────────────────────────────────────
 export * from "./I_AccessDenial";