@opencoredev/social-sdk 0.1.1 → 0.2.0

package/dist/platforms/instagram.js

@@ -1,6 +1,9 @@
+/* oxlint-disable anti-slop/no-conditional-empty-object-spread, anti-slop/no-known-value-widening, anti-slop/no-runtime-typeof, anti-slop/no-unsafe-dictionary-type, anti-slop/require-readable-spacing -- provider query and response boundaries are validated locally. */
 import { defineAdapter } from "../core/adapter.js";
 import { SocialError } from "../core/errors.js";
+import { profileRef } from "../core/types.js";
 import { managedHttp, publicFields } from "../cloud/common.js";
+import { HttpError } from "../transport/http.js";
 import { array, object, optionalNumber, optionalString, string } from "../transport/validation.js";
 import { httpsUrl } from "../transport/upload.js";
 class MemoryInstagramWorkflowStore {
@@ -34,12 +37,64 @@ class MemoryInstagramWorkflowStore {
 }
 export function instagram(options) {
     const apiVersion = "v25.0";
-    const request = managedHttp(`https://graph.instagram.com/${apiVersion}`, {
+    const flavor = options.auth.flavor ?? "instagram-login";
+    const origin = flavor === "facebook-login"
+        ? `https://graph.facebook.com/${apiVersion}`
+        : `https://graph.instagram.com/${apiVersion}`;
+    const request = managedHttp(origin, {
         apiKey: options.auth.accessToken,
+        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
         ...(options.fetch ? { fetch: options.fetch } : {}),
     });
     const now = () => (options.clock?.() ?? new Date()).toISOString();
     const workflows = options.workflowStore ?? new MemoryInstagramWorkflowStore();
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- provider payload is validated here.
+    const validatedObject = (value, operation) => {
+        try {
+            return object(value);
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.kind === "invalid-response")
+                throw new SocialError({
+                    code: "upstream_failure",
+                    operation,
+                    message: error.message,
+                    cause: error,
+                });
+            throw error;
+        }
+    };
+    const requireFacebookLogin = (operation) => {
+        if (flavor !== "facebook-login")
+            throw new SocialError({
+                code: "unsupported_capability",
+                operation,
+                message: `${operation} requires a Facebook Login Graph API access token for an Instagram professional account.`,
+                retryDisposition: { kind: "never" },
+            });
+    };
+    const pageLimit = (limit, max = 50) => {
+        const value = limit ?? 25;
+        if (!Number.isSafeInteger(value) || value < 1 || value > max)
+            throw new SocialError({
+                code: "invalid_input",
+                operation: "instagram.pagination",
+                message: `Instagram page limit must be an integer from 1 through ${max}.`,
+            });
+        return value;
+    };
+    const page = (result, fields) => {
+        const items = array(result["data"]).map((entry) => publicFields(entry, fields));
+        const paging = result["paging"] === undefined ? {} : object(result["paging"]);
+        const cursors = paging["cursors"] === undefined ? {} : object(paging["cursors"]);
+        // Graph API omits `paging.next` on the last page even when `cursors.after` is present.
+        const nextCursor = typeof paging["next"] === "string" &&
+            typeof cursors["after"] === "string" &&
+            cursors["after"].length > 0
+            ? cursors["after"]
+            : undefined;
+        return { items, ...(nextCursor === undefined ? {} : { nextCursor }) };
+    };
     const authorize = (ref, context) => {
         if (ref.backend !== context.backendInstance ||
             ref.platform !== "instagram" ||
@@ -47,7 +102,7 @@ export function instagram(options) {
             throw new SocialError({
                 code: "unauthorized",
                 operation: "instagram",
-                message: "Account reference does not match this Instagram Login authorization.",
+                message: "Account reference does not match this Instagram authorization.",
             });
     };
     const status = async (id, context) => object(await request(`/${encodeURIComponent(id)}`, context, undefined, {
@@ -62,6 +117,7 @@ export function instagram(options) {
                 operation: "posts.list",
                 message: "Instagram feed limit must be an integer from 1 through 100.",
             });
+        // oxlint-disable-next-line anti-slop/no-known-value-widening -- validated boundary or fixture contract.
         const query = {
             fields: "id,caption,media_type,media_product_type,permalink,timestamp,username",
         };
@@ -81,17 +137,23 @@ export function instagram(options) {
         ]));
         const paging = result["paging"] === undefined ? {} : object(result["paging"]);
         const cursors = paging["cursors"] === undefined ? {} : object(paging["cursors"]);
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
         const hasNext = typeof paging["next"] === "string" && paging["next"].length > 0;
-        const nextCursor = hasNext && typeof cursors["after"] === "string" ? cursors["after"] : undefined;
+        const nextCursor = 
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+        hasNext && typeof cursors["after"] === "string" ? cursors["after"] : undefined;
         return {
             items,
+            // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
             ...(nextCursor === undefined ? {} : { nextCursor }),
         };
     };
     const getAccountMetrics = async (selected, context) => {
         authorize(selected, context);
-        const result = object(await request("/me", context, undefined, {
-            fields: "user_id,followers_count,media_count",
+        const result = object(await request(flavor === "facebook-login" ? `/${encodeURIComponent(selected.accountId)}` : "/me", context, undefined, {
+            fields: flavor === "facebook-login"
+                ? "id,followers_count,media_count"
+                : "user_id,followers_count,media_count",
         }));
         const id = optionalString(result["user_id"]) ?? optionalString(result["id"]);
         if (id !== selected.accountId)
@@ -112,7 +174,7 @@ export function instagram(options) {
                         period: "lifetime",
                         fetchedAt: now(),
                         freshness: "unknown",
-                        source: "Instagram Login Graph v25.0",
+                        source: `${flavor === "facebook-login" ? "Facebook Login" : "Instagram Login"} Graph v25.0`,
                     },
                 ];
         });
@@ -148,7 +210,7 @@ export function instagram(options) {
                 backend: account.backend,
                 platform: "instagram",
                 accountId: account.accountId,
-                deliveryId: containerId,
+                deliveryId: workflowId ?? containerId,
             },
         };
         if (code === "IN_PROGRESS")
@@ -179,6 +241,7 @@ export function instagram(options) {
             await workflows.update(workflowId, { stage: "unknown" });
         let result;
         try {
+            // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
             result = object(await request(`/${encodeURIComponent(account.accountId)}/media_publish`, context, {
                 creation_id: containerId,
             }));
@@ -271,7 +334,11 @@ export function instagram(options) {
         }
     };
     const readAccount = async (context) => {
-        const response = object(await request("/me", context, undefined, { fields: "user_id,username,account_type" }));
+        const response = object(await request(flavor === "facebook-login" ? `/${encodeURIComponent(options.auth.accountId)}` : "/me", context, undefined, {
+            fields: flavor === "facebook-login"
+                ? "id,username,account_type"
+                : "user_id,username,account_type",
+        }));
         const id = optionalString(response["user_id"]) ?? optionalString(response["id"]);
         if (id !== options.auth.accountId)
             throw new SocialError({
@@ -291,12 +358,43 @@ export function instagram(options) {
             status: "connected",
         };
     };
+    const listMentions = async ({ account, cursor, limit, context, }) => {
+        authorize(account, context);
+        requireFacebookLogin("instagram.mentions.read");
+        const query = {
+            fields: "id,caption,media_type,media_product_type,permalink,timestamp,username",
+            limit: String(pageLimit(limit)),
+        };
+        if (cursor !== undefined)
+            query["after"] = cursor;
+        const result = validatedObject(await request(`/${encodeURIComponent(account.accountId)}/tags`, context, undefined, query), "instagram.mentions.read");
+        return page(result, [
+            "id",
+            "caption",
+            "media_type",
+            "media_product_type",
+            "permalink",
+            "timestamp",
+            "username",
+        ]);
+    };
+    const profileFields = [
+        "id",
+        "username",
+        "name",
+        "biography",
+        "profile_picture_url",
+        "followers_count",
+        "follows_count",
+        "media_count",
+        "website",
+    ];
     return defineAdapter({
         id: "instagram",
         capabilities: {
             schemaVersion: 1,
             backend: "instagram",
-            apiRevision: "Instagram Login Graph v25.0",
+            apiRevision: `${flavor === "facebook-login" ? "Facebook Login" : "Instagram Login"} Graph v25.0`,
             runtime: ["node22", "node24", "bun"],
             capabilities: [
                 {
@@ -304,7 +402,9 @@ export function instagram(options) {
                     operation: "posts.publish",
                     availability: "available",
                     formats: ["image", "video", "carousel"],
-                    requiredScopes: ["instagram_business_basic", "instagram_business_content_publish"],
+                    requiredScopes: flavor === "facebook-login"
+                        ? ["instagram_basic", "instagram_content_publish", "pages_read_engagement"]
+                        : ["instagram_business_basic", "instagram_business_content_publish"],
                     notes: "Professional accounts, public HTTPS media, explicit native continuation for processing containers. Carousels must have matching aspect ratios to avoid upstream cropping.",
                 },
                 ...[
@@ -315,11 +415,45 @@ export function instagram(options) {
                     "comments.read",
                     "comments.write",
                     "analytics.read",
+                    "analytics.account.read",
                 ].map((operation) => ({
                     operation,
                     platform: "instagram",
                     availability: "available",
                 })),
+                {
+                    platform: "instagram",
+                    operation: "comments.moderate",
+                    availability: "available",
+                    requiredScopes: flavor === "facebook-login"
+                        ? ["instagram_manage_comments", "pages_read_engagement"]
+                        : ["instagram_business_manage_comments"],
+                    notes: "Hide or unhide a comment, or enable or disable comments on media. Instagram Login and Facebook Login are supported where the account and app permissions qualify.",
+                },
+                {
+                    platform: "instagram",
+                    operation: "comments.delete",
+                    availability: "available",
+                    requiredScopes: flavor === "facebook-login"
+                        ? ["instagram_manage_comments", "pages_read_engagement"]
+                        : ["instagram_business_manage_comments"],
+                },
+                {
+                    platform: "instagram",
+                    operation: "comments.replies.read",
+                    availability: "available",
+                    requiredScopes: flavor === "facebook-login"
+                        ? ["instagram_manage_comments", "pages_read_engagement"]
+                        : ["instagram_business_manage_comments"],
+                },
+                {
+                    platform: "instagram",
+                    operation: "profiles.read",
+                    availability: "available",
+                    requiredScopes: flavor === "facebook-login"
+                        ? ["instagram_basic", "instagram_manage_insights", "pages_read_engagement"]
+                        : ["instagram_business_basic", "instagram_business_manage_insights"],
+                },
                 {
                     platform: "instagram",
                     operation: "reels.publish",
@@ -327,14 +461,60 @@ export function instagram(options) {
                     formats: ["video"],
                 },
                 { platform: "instagram", operation: "stories.publish", availability: "available" },
-                { platform: "instagram", operation: "posts.delete", availability: "available" },
-                { platform: "instagram", operation: "hashtags.search", availability: "available" },
+                {
+                    platform: "instagram",
+                    operation: "posts.delete",
+                    availability: flavor === "facebook-login"
+                        ? "available"
+                        : "not-implemented-by-adapter",
+                    ...(flavor === "facebook-login"
+                        ? { requiredScopes: ["instagram_basic", "pages_read_engagement"] }
+                        : {}),
+                },
+                {
+                    platform: "instagram",
+                    operation: "posts.removeFromPlatform",
+                    availability: flavor === "facebook-login"
+                        ? "available"
+                        : "not-implemented-by-adapter",
+                },
+                ...(flavor === "facebook-login"
+                    ? [
+                        {
+                            platform: "instagram",
+                            operation: "hashtags.search",
+                            availability: "available",
+                            requiredScopes: ["instagram_basic"],
+                            notes: "Requires Facebook Login, Instagram Public Content Access feature approval, and a qualifying Instagram professional account.",
+                        },
+                    ]
+                    : []),
                 {
                     platform: "instagram",
                     operation: "publishing.limit.read",
                     availability: "available",
                 },
-                { platform: "instagram", operation: "mentions.read", availability: "available" },
+                ...(flavor === "facebook-login"
+                    ? [
+                        {
+                            platform: "instagram",
+                            operation: "mentions.read",
+                            availability: "available",
+                            requiredScopes: [
+                                "instagram_basic",
+                                "instagram_manage_comments",
+                                "pages_read_engagement",
+                            ],
+                            notes: "Reads the paginated /{ig-user-id}/tags edge.",
+                        },
+                    ]
+                    : [
+                        {
+                            platform: "instagram",
+                            operation: "mentions.read",
+                            availability: "not-implemented-by-adapter",
+                        },
+                    ]),
                 {
                     platform: "instagram",
                     operation: "product.tagging",
@@ -422,11 +602,20 @@ export function instagram(options) {
                             ...(item.kind === "image"
                                 ? {
                                     image_url: item.source.url,
+                                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                                     ...(item.altText === undefined ? {} : { alt_text: item.altText }),
                                 }
                                 : {
                                     video_url: item.source.url,
                                     media_type: media.length > 1 ? "VIDEO" : "REELS",
+                                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- provider payload is validated at this adapter boundary.
+                                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated external boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated external boundary or fixture contract.
+                                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
                                     ...(typeof config["shareToFeed"] === "boolean"
                                         ? { share_to_feed: config["shareToFeed"] }
                                         : {}),
@@ -509,14 +698,7 @@ export function instagram(options) {
                                 postId: workflow.nativeId,
                             },
                         };
-                    if (workflow.stage === "unknown")
-                        return {
-                            ...processing(account, workflow.id, "AMBIGUOUS"),
-                            state: "unknown",
-                            reason: "ambiguous-submission",
-                            diagnostic: "Explicit resumePublication is required.",
-                        };
-                    return processing(account, workflow.id, workflow.stage.toUpperCase());
+                    return resumeWorkflow(workflow, account, context);
                 }
                 const result = await status(ref.deliveryId, context);
                 const code = string(result["status_code"]);
@@ -533,7 +715,12 @@ export function instagram(options) {
                     backendState: code,
                     delivery: { kind: "delivery", version: 1, ...ref },
                 };
-                if (code === "IN_PROGRESS" || code === "FINISHED")
+                if (code === "FINISHED") {
+                    const workflow = await workflows.get(ref.deliveryId);
+                    if (workflow)
+                        return resumeWorkflow(workflow, base.account, context);
+                }
+                if (code === "IN_PROGRESS")
                     return { ...base, state: "processing" };
                 if (code === "ERROR" || code === "EXPIRED")
                     return {
@@ -550,23 +737,23 @@ export function instagram(options) {
                     diagnostic: "Container status alone does not identify a published native post. Reconcile stored publish results.",
                 };
             },
+            async removeFromPlatform(ref, context) {
+                authorize(ref, context);
+                requireFacebookLogin("instagram.posts.removeFromPlatform");
+                await request(`/${encodeURIComponent(ref.postId)}`, context, undefined, {}, "DELETE");
+            },
         },
         comments: {
             async list(ref, input, context) {
-                if (input.cursor !== undefined)
-                    throw new SocialError({
-                        code: "unsupported_capability",
-                        operation: "comments.read",
-                        message: "This adapter does not expose upstream comment pagination.",
-                    });
                 authorize(ref, context);
-                const result = object(await request(`/${encodeURIComponent(ref.postId)}/comments`, context, undefined, {
+                const query = {
                     fields: "id,text,timestamp,username",
-                    limit: "25",
-                }));
-                return {
-                    items: array(result["data"]).map((entry) => publicFields(entry, ["id", "text", "timestamp", "username"])),
+                    limit: String(pageLimit(input.limit)),
                 };
+                if (input.cursor !== undefined)
+                    query["after"] = input.cursor;
+                const result = validatedObject(await request(`/${encodeURIComponent(ref.postId)}/comments`, context, undefined, query), "instagram.comments.read");
+                return page(result, ["id", "text", "timestamp", "username"]);
             },
             async reply(ref, content, context) {
                 authorize(ref, context);
@@ -580,9 +767,14 @@ export function instagram(options) {
             getAccountMetrics,
             async getPostMetrics(ref, context) {
                 authorize(ref, context);
-                const result = object(await request(`/${encodeURIComponent(ref.postId)}/insights`, context, undefined, {
-                    metric: "likes,comments,saved,shares,reach",
-                }));
+                const media = validatedObject(await request(`/${encodeURIComponent(ref.postId)}`, context, undefined, {
+                    fields: "media_product_type",
+                }), "instagram.analytics.read");
+                const result = validatedObject(await request(`/${encodeURIComponent(ref.postId)}/insights`, context, undefined, {
+                    metric: media["media_product_type"] === "STORY"
+                        ? "shares,reach"
+                        : "likes,comments,saved,shares,reach",
+                }), "instagram.analytics.read");
                 return array(result["data"]).flatMap((entry) => {
                     const row = object(entry);
                     const value = array(row["values"])[0];
@@ -605,7 +797,152 @@ export function instagram(options) {
                 });
             },
         },
+        graph: {
+            async getProfile(account, input, context) {
+                authorize(account, context);
+                let profile;
+                if (input.profileId === undefined && input.handle === undefined) {
+                    const own = validatedObject(await request(`/${encodeURIComponent(account.accountId)}`, context, undefined, {
+                        fields: flavor === "facebook-login"
+                            ? "id,username,name,biography,profile_picture_url,followers_count,follows_count,media_count,website"
+                            : "user_id,id,username,name,biography,profile_picture_url,followers_count,follows_count,media_count,website",
+                    }), "profiles.read");
+                    profile = publicFields(own, profileFields);
+                    const ownId = optionalString(own["user_id"]);
+                    if (ownId !== undefined)
+                        profile = { ...profile, id: ownId };
+                }
+                else if (input.profileId !== undefined) {
+                    profile = publicFields(await request(`/${encodeURIComponent(input.profileId)}`, context, undefined, {
+                        fields: "id,username,name,biography,profile_picture_url,followers_count,follows_count,media_count,website",
+                    }), profileFields);
+                }
+                else {
+                    requireFacebookLogin("instagram.profiles.read");
+                    const username = input.handle;
+                    if (username === undefined)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "profiles.read",
+                            message: "An Instagram profile ID or handle is required.",
+                        });
+                    if (!/^[A-Za-z0-9._]{1,30}$/.test(username))
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "profiles.read",
+                            message: "Instagram profile handles must contain only letters, numbers, periods, or underscores.",
+                        });
+                    const response = object(await request(`/${encodeURIComponent(account.accountId)}`, context, undefined, {
+                        fields: `business_discovery.username(${username}){id,username,name,biography,profile_picture_url,followers_count,follows_count,media_count,website}`,
+                    }));
+                    profile = publicFields(response["business_discovery"], [
+                        "id",
+                        "username",
+                        "name",
+                        "biography",
+                        "profile_picture_url",
+                        "followers_count",
+                        "follows_count",
+                        "media_count",
+                        "website",
+                    ]);
+                }
+                const id = string(profile["id"]);
+                return {
+                    ref: profileRef({
+                        backend: account.backend,
+                        platform: "instagram",
+                        accountId: account.accountId,
+                        profileId: id,
+                    }),
+                    ...(typeof profile["name"] === "string" ? { displayName: profile["name"] } : {}),
+                    ...(typeof profile["username"] === "string" ? { handle: profile["username"] } : {}),
+                    ...(typeof profile["profile_picture_url"] === "string"
+                        ? { avatarUrl: profile["profile_picture_url"] }
+                        : {}),
+                    ...(typeof profile["biography"] === "string" ? { bio: profile["biography"] } : {}),
+                    native: profile,
+                };
+            },
+        },
         native: {
+            async moderateComment({ account, commentId, hidden, context }) {
+                authorize(account, context);
+                await request(`/${encodeURIComponent(commentId)}`, context, undefined, { hide: String(hidden) }, "POST");
+            },
+            async deleteComment({ account, commentId, context }) {
+                authorize(account, context);
+                await request(`/${encodeURIComponent(commentId)}`, context, undefined, {}, "DELETE");
+            },
+            async setCommentsEnabled({ account, mediaId, enabled, context }) {
+                authorize(account, context);
+                await request(`/${encodeURIComponent(mediaId)}`, context, undefined, { comment_enabled: String(enabled) }, "POST");
+            },
+            async listCommentReplies({ account, commentId, cursor, limit, context }) {
+                authorize(account, context);
+                const query = {
+                    fields: "id,text,timestamp,username",
+                    limit: String(pageLimit(limit)),
+                };
+                if (cursor !== undefined)
+                    query["after"] = cursor;
+                return page(validatedObject(await request(`/${encodeURIComponent(commentId)}/replies`, context, undefined, query), "instagram.comments.replies.read"), ["id", "text", "timestamp", "username"]);
+            },
+            listMentions,
+            async mentionedMedia({ account, mediaId, context }) {
+                authorize(account, context);
+                requireFacebookLogin("instagram.mentions.read");
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated provider object boundary.
+                return validatedObject(await request(`/${encodeURIComponent(account.accountId)}`, context, undefined, {
+                    fields: `mentioned_media.media_id(${encodeURIComponent(mediaId)}){id,caption,media_type,media_url,timestamp,username,comments_count,like_count}`,
+                }), "instagram.mentions.read");
+            },
+            async mentionedComment({ account, commentId, context }) {
+                authorize(account, context);
+                requireFacebookLogin("instagram.mentions.read");
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated provider object boundary.
+                return validatedObject(await request(`/${encodeURIComponent(account.accountId)}`, context, undefined, {
+                    fields: `mentioned_comment.comment_id(${encodeURIComponent(commentId)}){id,text,timestamp,like_count,media}`,
+                }), "instagram.mentions.read");
+            },
+            async listTaggedMedia({ account, cursor, limit, context }) {
+                authorize(account, context);
+                requireFacebookLogin("instagram.mentions.read");
+                const query = {
+                    fields: "id,caption,media_type,permalink,timestamp,username",
+                    limit: String(pageLimit(limit)),
+                };
+                if (cursor !== undefined)
+                    query["after"] = cursor;
+                return page(validatedObject(await request(`/${encodeURIComponent(account.accountId)}/tags`, context, undefined, query), "instagram.mentions.read"), ["id", "caption", "media_type", "permalink", "timestamp", "username"]);
+            },
+            async hashtagMedia({ account, hashtagId, kind, cursor, limit, context }) {
+                authorize(account, context);
+                requireFacebookLogin("instagram.hashtags.search");
+                const query = {
+                    fields: "id,caption,media_type,permalink,timestamp,username",
+                    limit: String(pageLimit(limit, 50)),
+                };
+                if (cursor !== undefined)
+                    query["after"] = cursor;
+                return page(validatedObject(await request(`/${encodeURIComponent(hashtagId)}/${kind}_media`, context, undefined, query), "instagram.hashtags.search"), ["id", "caption", "media_type", "permalink", "timestamp", "username"]);
+            },
+            async businessDiscovery({ account, username, fields, context }) {
+                authorize(account, context);
+                requireFacebookLogin("instagram.profiles.businessDiscovery");
+                if (!/^[A-Za-z0-9._]{1,30}$/.test(username))
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "instagram.profiles.businessDiscovery",
+                        message: "Business discovery usernames must contain only letters, numbers, periods, or underscores.",
+                    });
+                const selectedFields = fields ??
+                    `business_discovery.username(${username}){id,username,name,biography,followers_count,media_count,profile_picture_url,media.limit(25){id,caption,media_type,permalink,timestamp}}`;
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated provider object boundary.
+                return object(await request(`/${encodeURIComponent(account.accountId)}`, context, undefined, {
+                    fields: selectedFields,
+                }));
+            },
             publishContainer,
             async publishCarousel(account, children, caption, context) {
                 authorize(account, context);
@@ -636,39 +973,58 @@ export function instagram(options) {
                 const created = object(await request(`/${encodeURIComponent(account.accountId)}/media`, context, {
                     media_type: "REELS",
                     video_url: videoUrl,
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(caption ? { caption } : {}),
                 }));
                 return publishContainer(account, string(created["id"]), context);
             },
-            async publishStory({ account, mediaUrl, context }) {
+            async publishStory({ account, mediaUrl, videoUrl, context }) {
                 authorize(account, context);
                 const created = object(await request(`/${encodeURIComponent(account.accountId)}/media`, context, {
                     media_type: "STORIES",
-                    image_url: mediaUrl,
+                    ...(videoUrl === undefined ? { image_url: mediaUrl } : { video_url: videoUrl }),
                 }));
                 return publishContainer(account, string(created["id"]), context);
             },
             async deletePost({ account, postId, context }) {
                 authorize(account, context);
+                requireFacebookLogin("instagram.posts.delete");
                 await request(`/${encodeURIComponent(postId)}`, context, undefined, {}, "DELETE");
             },
             async hashtagSearch({ account, hashtag, context }) {
                 authorize(account, context);
-                const tag = object(await request("/ig_hashtag_search", context, undefined, {
+                requireFacebookLogin("instagram.hashtags.search");
+                const normalized = hashtag.replace(/^#/, "").trim();
+                if (!normalized)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "instagram.hashtags.search",
+                        message: "Instagram hashtag search requires a non-empty hashtag name.",
+                    });
+                const result = validatedObject(await request("/ig_hashtag_search", context, undefined, {
                     user_id: account.accountId,
-                    q: hashtag.replace(/^#/, ""),
-                }));
-                return tag;
+                    q: normalized,
+                }), "instagram.hashtags.search");
+                return {
+                    data: array(result["data"]).map((entry) => {
+                        const row = object(entry);
+                        return { id: string(row["id"]) };
+                    }),
+                };
             },
             async publishingLimit({ account, context }) {
                 authorize(account, context);
+                // SAFETY: object() establishes an object response; this native method intentionally
+                // preserves Meta's provider-specific config object after validating its outer shape.
                 return object(await request(`/${encodeURIComponent(account.accountId)}/content_publishing_limit`, context, undefined, { fields: "config,quota_usage" }));
             },
-            async mentions({ account, context }) {
-                authorize(account, context);
-                return object(await request(`/${encodeURIComponent(account.accountId)}/tags`, context, undefined, {
-                    fields: "id,caption,media_type,timestamp",
-                }));
+            async mentions({ account, cursor, limit, context }) {
+                return listMentions({
+                    account,
+                    ...(cursor === undefined ? {} : { cursor }),
+                    ...(limit === undefined ? {} : { limit }),
+                    context,
+                });
             },
         },
     });