@opencoredev/social-sdk 0.1.1 → 0.2.0

package/dist/core/client.js

@@ -1,3 +1,4 @@
+/* oxlint-disable anti-slop/require-readable-spacing, anti-slop/no-conditional-empty-object-spread, anti-slop/require-safety-comment-for-type-assertion -- facade dispatch keeps capability-specific branches together. */
 import { decodeCursor, encodeCursor, iterateItems } from "./pagination.js";
 import { createConcurrencyLimiter } from "./concurrency.js";
 import { SocialError } from "./errors.js";
@@ -44,12 +45,10 @@ function mediaFingerprintView(content) {
     };
 }
 function preparationIssue(code, message, targetIndex) {
-    return {
-        code,
-        message,
-        severity: "error",
-        ...(targetIndex === undefined ? {} : { targetIndex }),
-    };
+    const issue = { code, message, severity: "error" };
+    if (targetIndex !== undefined)
+        Object.assign(issue, { targetIndex });
+    return issue;
 }
 function publicationStatus(outcomes) {
     const pending = new Set(["scheduled", "accepted", "processing"]);
@@ -76,16 +75,18 @@ async function mapConcurrent(count, concurrency, execute) {
     return results;
 }
 function makeContext(backendInstance, correlationId, options, targetIdempotencyKey) {
-    return {
+    const context = {
         backendInstance,
         correlationId,
         retryBudget: options?.retryBudget ?? { maxAttempts: 1, maxElapsedMs: 30_000 },
-        ...(options?.signal === undefined ? {} : { signal: options.signal }),
-        ...(options?.authorization === undefined ? {} : { authorization: options.authorization }),
-        ...(targetIdempotencyKey === undefined
-            ? {}
-            : { idempotencyKey: targetIdempotencyKey, targetIdempotencyKey }),
     };
+    if (options?.signal !== undefined)
+        Object.assign(context, { signal: options.signal });
+    if (options?.authorization !== undefined)
+        Object.assign(context, { authorization: options.authorization });
+    if (targetIdempotencyKey !== undefined)
+        Object.assign(context, { idempotencyKey: targetIdempotencyKey, targetIdempotencyKey });
+    return context;
 }
 function unsupported(operation, backend) {
     throw new SocialError({
@@ -95,7 +96,9 @@ function unsupported(operation, backend) {
         message: `${backend} does not implement ${operation}`,
     });
 }
-function outcomeFromError(error, target, observedAt) {
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- Adapter rejections enter the error boundary here.
+function outcomeFromError(error, // Transport and adapter rejections can be arbitrary JavaScript values.
+target, observedAt) {
     if (error instanceof SocialError) {
         if (error.code === "cancelled") {
             return {
@@ -183,7 +186,17 @@ export function createSocial(config) {
                 message: `Unknown backend instance: ${backend}`,
             });
         }
-        return limiter(signal, operation, work);
+        return limiter(signal, operation, work).catch((error) => {
+            if (error instanceof SocialError)
+                throw error;
+            throw new SocialError({
+                code: "upstream_failure",
+                operation,
+                backend,
+                message: "The adapter failed while processing the request",
+                cause: error,
+            });
+        });
     }
     const clock = config.clock ?? (() => new Date());
     let correlationSequence = 0;
@@ -250,10 +263,13 @@ export function createSocial(config) {
                 targetKey: key,
                 account: target.account,
                 content: mergeContent(request.content, target.content),
-                ...(target.options === undefined ? {} : { options: target.options }),
-                ...(request.schedule === undefined ? {} : { schedule: request.schedule }),
-                ...(replyTo === undefined ? {} : { replyTo }),
             };
+            if (target.options !== undefined)
+                Object.assign(prepared, { options: target.options });
+            if (request.schedule !== undefined)
+                Object.assign(prepared, { schedule: request.schedule });
+            if (replyTo !== undefined)
+                Object.assign(prepared, { replyTo });
             targets.push(prepared);
             try {
                 issues.push(...adapter.posts.prepareTarget(prepared));
@@ -284,6 +300,41 @@ export function createSocial(config) {
             });
         }
     }
+    async function authorizeRefWithFallback(operation, fallback, account, options, correlationId) {
+        try {
+            await authorizeRef(operation, account, options, correlationId);
+        }
+        catch (error) {
+            if (!(error instanceof SocialError) || error.code !== "unauthorized")
+                throw error;
+            await authorizeRef(fallback, account, options, correlationId);
+        }
+    }
+    function validateAccountRef(account, operation) {
+        if (account === null ||
+            typeof account !== "object" ||
+            account.kind !== "connected-account" ||
+            account.version !== 1 ||
+            typeof account.backend !== "string" ||
+            !account.backend.trim() ||
+            !account.platform ||
+            typeof account.accountId !== "string" ||
+            !account.accountId.trim())
+            throw new SocialError({
+                code: "invalid_input",
+                operation,
+                message: "A valid connected account reference is required",
+            });
+    }
+    function validDateOnly(value) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+            return false;
+        const parsed = new Date(`${value}T00:00:00Z`);
+        return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+    }
+    function validTimestamp(value) {
+        return typeof value === "string" && value.trim() !== "" && !Number.isNaN(Date.parse(value));
+    }
     function selected(ref, operation) {
         if (ref.kind !== undefined && (ref.kind === "" || ref.version !== 1)) {
             throw new SocialError({
@@ -497,18 +548,8 @@ export function createSocial(config) {
                 callOptions?.authorization?.tenantId ?? null,
                 callOptions?.limit ?? null,
             ]);
-            const received = await dispatch(first[0], callOptions?.signal, "accounts.read", () => first[1].accounts.list({
-                ...(callOptions?.cursor === undefined
-                    ? {}
-                    : { cursor: decodeCursor(cursorScope, callOptions.cursor) }),
-                ...(callOptions?.limit === undefined ? {} : { limit: callOptions.limit }),
-            }, makeContext(first[0], correlationId, callOptions)));
-            const page = {
-                ...received,
-                ...(received.nextCursor === undefined
-                    ? {}
-                    : { nextCursor: encodeCursor(cursorScope, received.nextCursor) }),
-            };
+            const received = await dispatch(first[0], callOptions?.signal, "accounts.read", () => first[1].accounts.list(decodePageOptions(cursorScope, callOptions), makeContext(first[0], correlationId, callOptions)));
+            const page = encodePage(cursorScope, received);
             if (config.authorization === undefined)
                 return page;
             const decisions = await config.authorization.authorizeTargets({
@@ -517,14 +558,17 @@ export function createSocial(config) {
                 context: makeContext(first[0], correlationId, callOptions),
             });
             const allowed = new Set(decisions.filter((item) => item.allowed).map((item) => targetKey(item.account)));
-            return {
+            const filtered = {
                 items: page.items.filter((item) => allowed.has(targetKey(item.ref))),
-                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
-                ...(page.metadata === undefined ? {} : { metadata: page.metadata }),
             };
+            if (page.nextCursor !== undefined)
+                Object.assign(filtered, { nextCursor: page.nextCursor });
+            if (page.metadata !== undefined)
+                Object.assign(filtered, { metadata: page.metadata });
+            return filtered;
         },
         iterate(callOptions) {
-            return iterateItems((cursor) => accountsFacade.list({ ...callOptions, ...(cursor === undefined ? {} : { cursor }) }), callOptions);
+            return iterateItems((cursor) => accountsFacade.list(iterationPageOptions(callOptions, cursor)), callOptions);
         },
         async get(ref, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
@@ -536,6 +580,137 @@ export function createSocial(config) {
             return dispatch(ref.backend, callOptions?.signal, "accounts.read", () => adapter.accounts.get(ref, makeContext(ref.backend, correlationId, callOptions)));
         },
     };
+    const graphFacade = {
+        async getProfile(account, input, callOptions) {
+            validateAccountRef(account, "profiles.read");
+            if (input === null ||
+                typeof input !== "object" ||
+                (input.profileId !== undefined &&
+                    input.handle !== undefined &&
+                    typeof input.profileId !== "string" &&
+                    typeof input.handle !== "string") ||
+                (input.profileId !== undefined &&
+                    (typeof input.profileId !== "string" || input.profileId.trim() === "")) ||
+                (input.handle !== undefined &&
+                    (typeof input.handle !== "string" || input.handle.trim() === "")))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "profiles.read",
+                    message: "Profile selector fields must be nonempty strings when provided",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("profiles.read", account, callOptions, correlationId);
+            const adapter = selected(account, "profiles.read");
+            requireCapability(adapter, "profiles.read", account.platform, account.backend);
+            if (adapter.graph?.getProfile === undefined)
+                unsupported("profiles.read", account.backend);
+            return dispatch(account.backend, callOptions?.signal, "profiles.read", () => adapter.graph.getProfile(account, input, makeContext(account.backend, correlationId, callOptions)));
+        },
+        async listRelationships(account, input, callOptions) {
+            validateAccountRef(account, "graph.read");
+            if (input === null ||
+                typeof input !== "object" ||
+                !["following", "followers", "blocked", "muted"].includes(input.kind) ||
+                (input.limit !== undefined && (!Number.isSafeInteger(input.limit) || input.limit < 1)))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "graph.read",
+                    message: !["following", "followers", "blocked", "muted"].includes(input?.kind)
+                        ? "Relationship kind must be following, followers, blocked, or muted"
+                        : "Relationship page limit must be a positive integer",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("graph.read", account, callOptions, correlationId);
+            const adapter = selected(account, "graph.read");
+            requireCapability(adapter, "graph.read", account.platform, account.backend);
+            if (adapter.graph?.listRelationships === undefined)
+                unsupported("graph.read", account.backend);
+            const scope = JSON.stringify([
+                account.backend,
+                "graph.read",
+                callOptions?.authorization?.tenantId ?? null,
+                account.platform,
+                account.accountId,
+                input.kind,
+                input.limit ?? null,
+            ]);
+            const page = await dispatch(account.backend, callOptions?.signal, "graph.read", () => adapter.graph.listRelationships(account, {
+                ...input,
+                ...(input.cursor === undefined ? {} : { cursor: decodeCursor(scope, input.cursor) }),
+            }, makeContext(account.backend, correlationId, callOptions)));
+            return encodePage(scope, page);
+        },
+        follow: (target, options) => graphMutation(target, "graph.follow", options),
+        unfollow: (target, options) => graphMutation(target, "graph.unfollow", options),
+        block: (target, options) => graphMutation(target, "graph.block", options),
+        unblock: (target, options) => graphMutation(target, "graph.unblock", options),
+        mute: (target, options) => graphMutation(target, "graph.mute", options),
+        unmute: (target, options) => graphMutation(target, "graph.unmute", options),
+    };
+    async function graphMutation(target, operation, callOptions) {
+        if (target === null ||
+            typeof target !== "object" ||
+            target.kind !== "profile" ||
+            target.version !== 1 ||
+            typeof target.backend !== "string" ||
+            target.backend.trim() === "" ||
+            typeof target.platform !== "string" ||
+            target.platform.trim() === "" ||
+            typeof target.accountId !== "string" ||
+            target.accountId.trim() === "" ||
+            typeof target.profileId !== "string" ||
+            target.profileId.trim() === "")
+            throw new SocialError({
+                code: "invalid_input",
+                operation,
+                message: "A valid profile reference is required",
+            });
+        const account = {
+            kind: "connected-account",
+            version: 1,
+            backend: target.backend,
+            platform: target.platform,
+            accountId: target.accountId,
+        };
+        const correlationId = `social-${++correlationSequence}`;
+        await authorizeRef(operation, account, callOptions, correlationId);
+        const adapter = selected(target, operation);
+        requireCapability(adapter, operation, target.platform, target.backend);
+        if (adapter.graph === undefined)
+            unsupported(operation, target.backend);
+        const context = makeContext(target.backend, correlationId, callOptions);
+        return dispatch(target.backend, callOptions?.signal, operation, async () => {
+            switch (operation) {
+                case "graph.follow":
+                    if (adapter.graph.follow === undefined)
+                        unsupported(operation, target.backend);
+                    return await adapter.graph.follow(target, context);
+                case "graph.unfollow":
+                    if (adapter.graph.unfollow === undefined)
+                        unsupported(operation, target.backend);
+                    await adapter.graph.unfollow(target, context);
+                    return undefined;
+                case "graph.block":
+                    if (adapter.graph.block === undefined)
+                        unsupported(operation, target.backend);
+                    return await adapter.graph.block(target, context);
+                case "graph.unblock":
+                    if (adapter.graph.unblock === undefined)
+                        unsupported(operation, target.backend);
+                    await adapter.graph.unblock(target, context);
+                    return undefined;
+                case "graph.mute":
+                    if (adapter.graph.mute === undefined)
+                        unsupported(operation, target.backend);
+                    return await adapter.graph.mute(target, context);
+                case "graph.unmute":
+                    if (adapter.graph.unmute === undefined)
+                        unsupported(operation, target.backend);
+                    await adapter.graph.unmute(target, context);
+                    return undefined;
+            }
+        });
+    }
     async function lifecycle(ref, expectedKind, operation, callOptions) {
         if (ref.kind !== expectedKind || ref.version !== 1 || !ref.accountId || !ref.platform)
             throw new SocialError({
@@ -571,25 +746,12 @@ export function createSocial(config) {
                 account.accountId,
                 callOptions?.limit ?? null,
             ]);
-            const input = {
-                ...(callOptions?.cursor === undefined
-                    ? {}
-                    : { cursor: decodeCursor(scope, callOptions.cursor) }),
-                ...(callOptions?.limit === undefined ? {} : { limit: callOptions.limit }),
-            };
+            const input = decodePageOptions(scope, callOptions);
             const page = await dispatch(account.backend, callOptions?.signal, "posts.list", () => adapter.posts.list(account, input, makeContext(account.backend, correlationId, callOptions)));
-            return {
-                ...page,
-                ...(page.nextCursor === undefined
-                    ? {}
-                    : { nextCursor: encodeCursor(scope, page.nextCursor) }),
-            };
+            return encodePage(scope, page);
         },
         iterate(account, callOptions) {
-            return iterateItems((cursor) => postsFacade.list(account, {
-                ...callOptions,
-                ...(cursor === undefined ? {} : { cursor }),
-            }), callOptions);
+            return iterateItems((cursor) => postsFacade.list(account, iterationPageOptions(callOptions, cursor)), callOptions);
         },
         async cancelScheduled(ref, callOptions) {
             const { adapter, context } = await lifecycle(ref, "scheduled-job", "posts.cancelScheduled", callOptions);
@@ -618,25 +780,105 @@ export function createSocial(config) {
                     operation: "posts.publishSequence",
                     message: "A sequence requires at least one item",
                 });
-            const results = [];
+            if (typeof request.idempotencyKey !== "string" || request.idempotencyKey.trim() === "")
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "posts.publishSequence",
+                    message: "A nonempty idempotencyKey is required",
+                });
+            const prepared = [];
             for (const [index, item] of request.items.entries()) {
-                const result = await publish({
+                const publishRequest = {
                     targets: item.targets,
                     content: item.content,
                     idempotencyKey: `${request.idempotencyKey}:${index}`,
-                    ...(item.replyTo === undefined ? {} : { replyTo: item.replyTo }),
-                }, callOptions);
+                };
+                if (item.replyTo !== undefined)
+                    Object.assign(publishRequest, { replyTo: item.replyTo });
+                const chained = request.replyToPrevious === true && index > 0;
+                if (chained) {
+                    const account = item.targets[0]?.account;
+                    const parent = request.items[index - 1]?.targets[0]?.account;
+                    // A chain replies to the single post the previous item created, so every link
+                    // must publish to one target on the same account.
+                    if (item.targets.length !== 1 ||
+                        request.items[index - 1]?.targets.length !== 1 ||
+                        item.replyTo !== undefined ||
+                        item.targets[0]?.replyTo !== undefined ||
+                        account === undefined ||
+                        parent === undefined ||
+                        account.backend !== parent.backend ||
+                        account.platform !== parent.platform ||
+                        account.accountId !== parent.accountId)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "posts.publishSequence",
+                            message: "replyToPrevious requires every item to publish to the same single account without its own replyTo",
+                        });
+                }
+                const plan = prepare(chained
+                    ? {
+                        ...publishRequest,
+                        // Placeholder parent so adapters validate reply support before anything is sent.
+                        replyTo: {
+                            kind: "platform-post",
+                            version: 1,
+                            backend: item.targets[0].account.backend,
+                            platform: item.targets[0].account.platform,
+                            accountId: item.targets[0].account.accountId,
+                            postId: "preflight",
+                        },
+                    }
+                    : publishRequest);
+                if (!plan.ok)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "posts.publishSequence",
+                        message: "Publication preparation failed; no targets were dispatched",
+                        issues: plan.issues,
+                    });
+                for (const target of plan.targets)
+                    await authorizeRef("posts.publish", target.account, callOptions, `social-${++correlationSequence}`);
+                prepared.push(publishRequest);
+            }
+            const results = [];
+            const failures = [];
+            let previous;
+            for (const [index, publishRequest] of prepared.entries()) {
+                const chained = request.replyToPrevious === true && index > 0;
+                // Without a published parent the item would post as an unrelated root post.
+                if (chained && previous === undefined)
+                    break;
+                const nextRequest = chained && previous !== undefined
+                    ? { ...publishRequest, replyTo: previous }
+                    : publishRequest;
+                let result;
+                previous = undefined;
+                try {
+                    result = await publish(nextRequest, callOptions);
+                }
+                catch (error) {
+                    if (error instanceof SocialError) {
+                        failures.push({ index, code: error.code, message: error.message });
+                        if (request.stopOnFailure !== false)
+                            break;
+                        continue;
+                    }
+                    throw error;
+                }
                 results.push(result);
-                if (request.stopOnFailure !== false && result.status !== "complete")
+                const published = result.outcomes.find((outcome) => outcome.state === "published");
+                if (published?.post !== undefined)
+                    previous = published.post;
+                if (request.stopOnFailure !== false && result.status === "partial")
                     break;
             }
-            const status = results.length === request.items.length &&
-                results.every((item) => item.status === "complete")
-                ? "complete"
-                : results.some((item) => item.status === "partial") || results.length > 0
-                    ? "partial"
+            const status = results.length < request.items.length || results.some((item) => item.status === "partial")
+                ? "partial"
+                : results.every((item) => item.status === "complete")
+                    ? "complete"
                     : "pending";
-            return { status, items: results };
+            return { status, items: results, failures };
         },
         async get(ref, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
@@ -666,10 +908,61 @@ export function createSocial(config) {
             const adapter = selected(ref, "posts.getDelivery");
             requireCapability(adapter, "posts.status", ref.platform, ref.backend);
             if (adapter.posts?.getDelivery === undefined)
-                unsupported("posts.read", ref.backend);
+                unsupported("posts.status", ref.backend);
             return dispatch(ref.backend, callOptions?.signal, "posts.status", () => adapter.posts.getDelivery(ref, makeContext(ref.backend, correlationId, callOptions)));
         },
     };
+    const searchFacade = {
+        async posts(account, input, callOptions) {
+            validateAccountRef(account, "search.posts");
+            if (input === null ||
+                input === undefined ||
+                typeof input.query !== "string" ||
+                !input.query.trim() ||
+                (input.limit !== undefined && (!Number.isSafeInteger(input.limit) || input.limit < 1)) ||
+                (input.startTime !== undefined &&
+                    (typeof input.startTime !== "string" || !validTimestamp(input.startTime))) ||
+                (input.endTime !== undefined &&
+                    (typeof input.endTime !== "string" || !validTimestamp(input.endTime))) ||
+                (input.startTime !== undefined &&
+                    input.endTime !== undefined &&
+                    Date.parse(input.startTime) > Date.parse(input.endTime)) ||
+                (input.scope !== undefined && input.scope !== "recent" && input.scope !== "all"))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "search.posts",
+                    message: "Search requires an account reference, a nonempty query, and a positive page limit.",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("search.posts", account, callOptions, correlationId);
+            const adapter = selected(account, "search.posts");
+            requireCapability(adapter, "search.posts", account.platform, account.backend);
+            const search = adapter.search;
+            if (search === undefined)
+                unsupported("search.posts", account.backend);
+            const scope = await fingerprint([
+                account.backend,
+                "search.posts",
+                callOptions?.authorization?.tenantId ?? null,
+                account.platform,
+                account.accountId,
+                input.query,
+                input.limit ?? null,
+                input.startTime ?? null,
+                input.endTime ?? null,
+                input.scope ?? "recent",
+            ]);
+            const providerInput = { ...input };
+            if (input.cursor !== undefined) {
+                Object.assign(providerInput, { cursor: decodeCursor(scope, input.cursor) });
+            }
+            const page = await dispatch(account.backend, callOptions?.signal, "search.posts", () => search.posts(account, providerInput, makeContext(account.backend, correlationId, callOptions)));
+            return encodePage(scope, page);
+        },
+        iteratePosts(account, input, callOptions) {
+            return iterateItems((cursor) => searchFacade.posts(account, { ...input, ...iterationPageOptions(undefined, cursor) }, callOptions), callOptions);
+        },
+    };
     const mediaFacade = {
         async upload(input, account, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
@@ -683,8 +976,9 @@ export function createSocial(config) {
     };
     const analyticsFacade = {
         async getAccountMetrics(ref, callOptions) {
+            validateAccountRef(ref, "analytics.account.read");
             const correlationId = `social-${++correlationSequence}`;
-            await authorizeRef("analytics.read", ref, callOptions, correlationId);
+            await authorizeRefWithFallback("analytics.account.read", "analytics.read", ref, callOptions, correlationId);
             const adapter = selected(ref, "analytics.getAccountMetrics");
             requireCapability(adapter, "analytics.account.read", ref.platform, ref.backend);
             if (!adapter.analytics?.getAccountMetrics)
@@ -707,10 +1001,47 @@ export function createSocial(config) {
                 unsupported("analytics.read", ref.backend);
             return dispatch(ref.backend, callOptions?.signal, "analytics.read", () => adapter.analytics.getPostMetrics(ref, makeContext(ref.backend, correlationId, callOptions)));
         },
+        async getReport(ref, query, callOptions) {
+            validateAccountRef(ref, "analytics.report.read");
+            if (query === undefined ||
+                query === null ||
+                !validDateOnly(query.from) ||
+                !validDateOnly(query.to) ||
+                query.from > query.to ||
+                !Array.isArray(query.metrics) ||
+                query.metrics.length === 0 ||
+                query.metrics.some(
+                // oxlint-disable-next-line anti-slop/no-runtime-typeof -- runtime query boundary.
+                (metric) => typeof metric !== "string" || !metric.trim()) ||
+                (query.dimensions !== undefined &&
+                    (!Array.isArray(query.dimensions) ||
+                        query.dimensions.some(
+                        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- runtime query boundary.
+                        (dimension) => typeof dimension !== "string" || !dimension.trim()))))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "analytics.report.read",
+                    message: "Reports require an ordered YYYY-MM-DD range, at least one metric, and nonempty dimensions.",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("analytics.report.read", ref, callOptions, correlationId);
+            const adapter = selected(ref, "analytics.getReport");
+            requireCapability(adapter, "analytics.report.read", ref.platform, ref.backend);
+            if (!adapter.analytics?.getReport)
+                unsupported("analytics.report.read", ref.backend);
+            return dispatch(ref.backend, callOptions?.signal, "analytics.report.read", () => adapter.analytics.getReport(ref, query, makeContext(ref.backend, correlationId, callOptions)));
+        },
     };
     const commentsFacade = {
         async list(ref, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
+            if (callOptions?.limit !== undefined &&
+                (!Number.isSafeInteger(callOptions.limit) || callOptions.limit < 1))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "comments.read",
+                    message: "Comment page limit must be a positive integer",
+                });
             const account = {
                 kind: "connected-account",
                 version: 1,
@@ -732,21 +1063,11 @@ export function createSocial(config) {
                 ref.postId,
                 callOptions?.limit ?? null,
             ]);
-            const received = await dispatch(ref.backend, callOptions?.signal, "comments.read", () => adapter.comments.list(ref, {
-                ...(callOptions?.cursor === undefined
-                    ? {}
-                    : { cursor: decodeCursor(cursorScope, callOptions.cursor) }),
-                ...(callOptions?.limit === undefined ? {} : { limit: callOptions.limit }),
-            }, makeContext(ref.backend, correlationId, callOptions)));
-            return {
-                ...received,
-                ...(received.nextCursor === undefined
-                    ? {}
-                    : { nextCursor: encodeCursor(cursorScope, received.nextCursor) }),
-            };
+            const received = await dispatch(ref.backend, callOptions?.signal, "comments.read", () => adapter.comments.list(ref, decodePageOptions(cursorScope, callOptions), makeContext(ref.backend, correlationId, callOptions)));
+            return encodePage(cursorScope, received);
         },
         iterate(ref, callOptions) {
-            return iterateItems((cursor) => commentsFacade.list(ref, { ...callOptions, ...(cursor === undefined ? {} : { cursor }) }), callOptions);
+            return iterateItems((cursor) => commentsFacade.list(ref, iterationPageOptions(callOptions, cursor)), callOptions);
         },
         async reply(ref, content, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
@@ -768,6 +1089,13 @@ export function createSocial(config) {
     const messagesFacade = {
         async listConversations(account, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
+            if (callOptions?.limit !== undefined &&
+                (!Number.isSafeInteger(callOptions.limit) || callOptions.limit < 1))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "messages.read",
+                    message: "Message page limit must be a positive integer",
+                });
             await authorizeRef("messages.read", account, callOptions, correlationId);
             const adapter = selected(account, "messages.listConversations");
             requireCapability(adapter, "messages.read", account.platform, account.backend);
@@ -782,27 +1110,21 @@ export function createSocial(config) {
                 "conversations",
                 callOptions?.limit ?? null,
             ]);
-            const received = await dispatch(account.backend, callOptions?.signal, "messages.read", () => adapter.messages.listConversations(account, {
-                ...(callOptions?.cursor === undefined
-                    ? {}
-                    : { cursor: decodeCursor(cursorScope, callOptions.cursor) }),
-                ...(callOptions?.limit === undefined ? {} : { limit: callOptions.limit }),
-            }, makeContext(account.backend, correlationId, callOptions)));
-            return {
-                ...received,
-                ...(received.nextCursor === undefined
-                    ? {}
-                    : { nextCursor: encodeCursor(cursorScope, received.nextCursor) }),
-            };
+            const received = await dispatch(account.backend, callOptions?.signal, "messages.read", () => adapter.messages.listConversations(account, decodePageOptions(cursorScope, callOptions), makeContext(account.backend, correlationId, callOptions)));
+            return encodePage(cursorScope, received);
         },
         iterateConversations(account, callOptions) {
-            return iterateItems((cursor) => messagesFacade.listConversations(account, {
-                ...callOptions,
-                ...(cursor === undefined ? {} : { cursor }),
-            }), callOptions);
+            return iterateItems((cursor) => messagesFacade.listConversations(account, iterationPageOptions(callOptions, cursor)), callOptions);
         },
         async listMessages(ref, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
+            if (callOptions?.limit !== undefined &&
+                (!Number.isSafeInteger(callOptions.limit) || callOptions.limit < 1))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "messages.read",
+                    message: "Message page limit must be a positive integer",
+                });
             const account = {
                 kind: "connected-account",
                 version: 1,
@@ -824,24 +1146,11 @@ export function createSocial(config) {
                 ref.conversationId,
                 callOptions?.limit ?? null,
             ]);
-            const received = await dispatch(ref.backend, callOptions?.signal, "messages.read", () => adapter.messages.listMessages(ref, {
-                ...(callOptions?.cursor === undefined
-                    ? {}
-                    : { cursor: decodeCursor(cursorScope, callOptions.cursor) }),
-                ...(callOptions?.limit === undefined ? {} : { limit: callOptions.limit }),
-            }, makeContext(ref.backend, correlationId, callOptions)));
-            return {
-                ...received,
-                ...(received.nextCursor === undefined
-                    ? {}
-                    : { nextCursor: encodeCursor(cursorScope, received.nextCursor) }),
-            };
+            const received = await dispatch(ref.backend, callOptions?.signal, "messages.read", () => adapter.messages.listMessages(ref, decodePageOptions(cursorScope, callOptions), makeContext(ref.backend, correlationId, callOptions)));
+            return encodePage(cursorScope, received);
         },
         iterateMessages(ref, callOptions) {
-            return iterateItems((cursor) => messagesFacade.listMessages(ref, {
-                ...callOptions,
-                ...(cursor === undefined ? {} : { cursor }),
-            }), callOptions);
+            return iterateItems((cursor) => messagesFacade.listMessages(ref, iterationPageOptions(callOptions, cursor)), callOptions);
         },
         async send(ref, content, callOptions) {
             const correlationId = `social-${++correlationSequence}`;
@@ -860,13 +1169,65 @@ export function createSocial(config) {
             return dispatch(ref.backend, callOptions?.signal, "messages.write", () => adapter.messages.send(ref, content, makeContext(ref.backend, correlationId, callOptions)));
         },
     };
+    const notificationsFacade = {
+        async list(account, callOptions) {
+            validateAccountRef(account, "notifications.read");
+            if (callOptions?.limit !== undefined &&
+                (!Number.isSafeInteger(callOptions.limit) || callOptions.limit < 1))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "notifications.read",
+                    message: "Notification page limit must be a positive integer",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("notifications.read", account, callOptions, correlationId);
+            const adapter = selected(account, "notifications.list");
+            requireCapability(adapter, "notifications.read", account.platform, account.backend);
+            if (adapter.notifications === undefined)
+                unsupported("notifications.read", account.backend);
+            const cursorScope = JSON.stringify([
+                account.backend,
+                "notifications.read",
+                callOptions?.authorization?.tenantId ?? null,
+                account.platform,
+                account.accountId,
+                callOptions?.limit ?? null,
+            ]);
+            const received = await dispatch(account.backend, callOptions?.signal, "notifications.read", () => adapter.notifications.list(account, decodePageOptions(cursorScope, callOptions), makeContext(account.backend, correlationId, callOptions)));
+            return encodePage(cursorScope, received);
+        },
+        iterate(account, callOptions) {
+            return iterateItems((cursor) => notificationsFacade.list(account, iterationPageOptions(callOptions, cursor)), callOptions);
+        },
+        async markSeen(account, input = {}, callOptions) {
+            validateAccountRef(account, "notifications.seen");
+            if (input === null ||
+                typeof input !== "object" ||
+                (input.seenAt !== undefined && !validTimestamp(input.seenAt)))
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "notifications.seen",
+                    message: "seenAt must be a valid timestamp",
+                });
+            const correlationId = `social-${++correlationSequence}`;
+            await authorizeRef("notifications.seen", account, callOptions, correlationId);
+            const adapter = selected(account, "notifications.markSeen");
+            requireCapability(adapter, "notifications.seen", account.platform, account.backend);
+            if (adapter.notifications === undefined)
+                unsupported("notifications.seen", account.backend);
+            return dispatch(account.backend, callOptions?.signal, "notifications.seen", () => adapter.notifications.markSeen(account, input, makeContext(account.backend, correlationId, callOptions)));
+        },
+    };
     return {
         accounts: accountsFacade,
+        graph: graphFacade,
         posts: postsFacade,
+        search: searchFacade,
         media: mediaFacade,
         analytics: analyticsFacade,
         comments: commentsFacade,
         messages: messagesFacade,
+        notifications: notificationsFacade,
         capabilities: () => Object.fromEntries(entries.map(([key, adapter]) => [key, adapter.capabilities])),
         adapter: (backend, acknowledgement) => {
             if (acknowledgement?.acknowledgeUnsafe !== true)
@@ -877,17 +1238,49 @@ export function createSocial(config) {
                 });
             const selected = registry[String(backend)];
             if (selected === undefined)
-                throw new Error(`Unknown backend: ${String(backend)}`);
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "adapter",
+                    message: `Unknown backend: ${String(backend)}`,
+                });
             return selected;
         },
         native: (backend, acknowledgement) => {
             if (acknowledgement?.acknowledgeUnsafe !== true)
-                throw new Error("Native access requires acknowledgeUnsafe: true");
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "native",
+                    message: "Native access requires acknowledgeUnsafe: true",
+                });
             const selected = registry[String(backend)];
             if (selected === undefined)
-                throw new Error(`Unknown backend: ${String(backend)}`);
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "native",
+                    message: `Unknown backend: ${String(backend)}`,
+                });
             return selected.native;
         },
     };
 }
+function decodePageOptions(scope, options) {
+    const input = {};
+    if (options?.cursor !== undefined)
+        input.cursor = decodeCursor(scope, options.cursor);
+    if (options?.limit !== undefined)
+        input.limit = options.limit;
+    return input;
+}
+function encodePage(scope, page) {
+    const result = { ...page };
+    if (page.nextCursor !== undefined)
+        result.nextCursor = encodeCursor(scope, page.nextCursor);
+    return result;
+}
+function iterationPageOptions(options, cursor) {
+    const result = { ...options };
+    if (cursor !== undefined)
+        result.cursor = cursor;
+    return result;
+}
 //# sourceMappingURL=client.js.map