@rocapine/rn-social-share 0.1.0

package/src/channels/index.ts

@@ -0,0 +1,8 @@
+export { systemSheet } from "./systemSheet";
+export { whatsapp } from "./whatsapp";
+export { copyLink } from "./copyLink";
+export { instagramStories } from "./instagramStories";
+export { sms } from "./sms";
+export { tiktok, type TikTokChannelOptions } from "./tiktok";
+export { saveToLibrary } from "./saveToLibrary";
+export { openSystemShareSheet } from "./_shareSheet";

package/src/channels/instagramStories.ts

@@ -0,0 +1,40 @@
+import { Linking } from "react-native";
+import Share, { type ShareSingleOptions } from "react-native-share";
+import type { ShareChannel } from "../types";
+
+const INSTAGRAM_STORIES_URL = "instagram-stories://share";
+
+/**
+ * Instagram Stories with the captured image as the full-bleed background.
+ *
+ * `appId` is required and app-specific — it is the Facebook/Meta App ID tied to your app
+ * (mandatory for the Stories deep link since Jan 2023). Pass your own; the two apps that
+ * seeded this package use different ids.
+ *
+ * iOS: requires `instagram-stories` in LSApplicationQueriesSchemes (see `withSocialShare`)
+ * for `isAvailable` to detect Instagram. When unavailable, `createSharer` routes to the
+ * fallback channel.
+ */
+export const instagramStories = (options: { appId: string; id?: string }): ShareChannel => {
+  const id = options.id ?? "instagram";
+  return {
+    id,
+    isAvailable: async (payload) => {
+      if (!payload.imageUri) {
+        return false;
+      }
+      return Linking.canOpenURL(INSTAGRAM_STORIES_URL).catch(() => false);
+    },
+    share: async (payload) => {
+      if (!payload.imageUri) {
+        throw new Error("[rn-social-share] instagramStories requires payload.imageUri");
+      }
+      await Share.shareSingle({
+        social: Share.Social.INSTAGRAM_STORIES,
+        backgroundImage: payload.imageUri,
+        appId: options.appId,
+      } as ShareSingleOptions);
+      return { completed: true, channel: id };
+    },
+  };
+};

package/src/channels/saveToLibrary.ts

@@ -0,0 +1,36 @@
+import type { ShareChannel } from "../types";
+
+/**
+ * Saves the image to the device photo library via `expo-media-library` (add-only / write
+ * permission, which avoids needing a full photo-library read description on iOS). Returns
+ * `{ completed: false, permissionDenied: true }` when the user denies access, so the host UI
+ * can show an "open settings" prompt.
+ *
+ * `expo-media-library` is a lazy require and optional — only apps that register this channel
+ * need it installed.
+ */
+export const saveToLibrary = (options: { id?: string } = {}): ShareChannel => {
+  const id = options.id ?? "save";
+  return {
+    id,
+    isAvailable: async (payload) => Boolean(payload.imageUri),
+    share: async (payload) => {
+      if (!payload.imageUri) {
+        throw new Error("[rn-social-share] saveToLibrary requires payload.imageUri");
+      }
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const MediaLibrary = require("expo-media-library");
+      const current = await MediaLibrary.getPermissionsAsync(true);
+      let granted = current.granted;
+      if (!granted) {
+        const requested = await MediaLibrary.requestPermissionsAsync(true);
+        granted = requested.granted;
+      }
+      if (!granted) {
+        return { completed: false, channel: id, permissionDenied: true };
+      }
+      await MediaLibrary.saveToLibraryAsync(payload.imageUri);
+      return { completed: true, channel: id };
+    },
+  };
+};

package/src/channels/sms.ts

@@ -0,0 +1,23 @@
+import Share, { type ShareSingleOptions } from "react-native-share";
+import type { ShareChannel } from "../types";
+
+/**
+ * Native SMS/Messages composer with the full text body and the card image attached.
+ * `isAvailable` is optimistic (true); a device without SMS makes `shareSingle` throw, and
+ * `createSharer` then routes to the fallback channel.
+ */
+export const sms = (options: { id?: string } = {}): ShareChannel => {
+  const id = options.id ?? "messages";
+  return {
+    id,
+    isAvailable: async () => true,
+    share: async (payload) => {
+      await Share.shareSingle({
+        social: Share.Social.SMS,
+        message: payload.message,
+        url: payload.imageUri,
+      } as ShareSingleOptions);
+      return { completed: true, channel: id };
+    },
+  };
+};

package/src/channels/systemSheet.ts

@@ -0,0 +1,15 @@
+import type { ShareChannel } from "../types";
+import { openSystemShareSheet } from "./_shareSheet";
+
+/**
+ * The generic native share sheet. Always available, so it doubles as the default fallback
+ * (register it with the default id "system-sheet" to have `createSharer` pick it up).
+ */
+export const systemSheet = (options: { id?: string } = {}): ShareChannel => {
+  const id = options.id ?? "system-sheet";
+  return {
+    id,
+    isAvailable: async () => true,
+    share: (payload) => openSystemShareSheet(payload, id),
+  };
+};

package/src/channels/tiktok.ts

@@ -0,0 +1,56 @@
+import type { ShareChannel } from "../types";
+import { openSystemShareSheet } from "./_shareSheet";
+
+export type TikTokChannelOptions = {
+  id?: string;
+  /** Called if the OpenSDK is missing or rejects (before falling back to the system sheet). */
+  onError?: (error: unknown) => void;
+};
+
+/**
+ * TikTok via `tiktok-opensdk-react-native`, fire-and-forget. Opening TikTok IS the action —
+ * we never await the SDK's result promise because, with no AppDelegate callback wired, it
+ * may never settle. We report `completed` optimistically once the share is kicked off; a
+ * *real* rejection (e.g. TikTok not installed) still routes to the system sheet so the user
+ * can share.
+ *
+ * The SDK is a lazy require and optional: if it isn't installed, this channel simply falls
+ * back to the system sheet. Native setup (client key, FileProvider, package visibility)
+ * lives in the app's own TikTok config plugin — see the README.
+ *
+ * API (tiktok-opensdk-react-native@0.10.x): default export
+ *   TikTokOpenSDK.share(mediaPaths: string[], isImage?: boolean, isGreenScreen?: boolean)
+ */
+export const tiktok = (options: TikTokChannelOptions = {}): ShareChannel => {
+  const id = options.id ?? "tiktok";
+
+  const fallback = (payload: Parameters<ShareChannel["share"]>[0]) =>
+    openSystemShareSheet(payload, id).then((outcome) => ({ ...outcome, fellBack: true }));
+
+  return {
+    id,
+    isAvailable: async (payload) => Boolean(payload.imageUri),
+    share: async (payload) => {
+      if (!payload.imageUri) {
+        return fallback(payload);
+      }
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require("tiktok-opensdk-react-native");
+        const TikTokOpenSDK = mod?.default ?? mod;
+        if (TikTokOpenSDK && typeof TikTokOpenSDK.share === "function") {
+          // Fire-and-forget. Fall back only on a real rejection; the promise-never-settles
+          // case simply never runs `.catch`, which is the intended behavior.
+          TikTokOpenSDK.share([payload.imageUri], true, false).catch((error: unknown) => {
+            options.onError?.(error);
+            void openSystemShareSheet(payload, id);
+          });
+          return { completed: true, channel: id };
+        }
+      } catch (error) {
+        options.onError?.(error);
+      }
+      return fallback(payload);
+    },
+  };
+};

package/src/channels/whatsapp.ts

@@ -0,0 +1,24 @@
+import { Linking } from "react-native";
+import type { ShareChannel } from "../types";
+import { openSystemShareSheet } from "./_shareSheet";
+
+const WHATSAPP_PROBE_URL = "whatsapp://send";
+
+/**
+ * WhatsApp — intentionally routed through the system share sheet. iOS has no reliable
+ * direct deep link that carries the full text AND an image: both `whatsapp://send?text=`
+ * and `wa.me` drop everything but the URL on real devices, and RNShare's WhatsApp-text
+ * path builds an invalid URL (literal spaces). The share sheet's WhatsApp extension is the
+ * only dependable path. `isAvailable` still probes for the app so the UI can hide the
+ * button when WhatsApp isn't installed.
+ *
+ * iOS: requires `whatsapp` in LSApplicationQueriesSchemes (see `withSocialShare`).
+ */
+export const whatsapp = (options: { id?: string } = {}): ShareChannel => {
+  const id = options.id ?? "whatsapp";
+  return {
+    id,
+    isAvailable: () => Linking.canOpenURL(WHATSAPP_PROBE_URL).catch(() => false),
+    share: (payload) => openSystemShareSheet(payload, id),
+  };
+};

package/src/createSharer.ts

@@ -0,0 +1,119 @@
+import type {
+  CreateSharerOptions,
+  ShareChannel,
+  ShareEvent,
+  SharePayload,
+  ShareOutcome,
+  Sharer,
+} from "./types";
+
+const DEFAULT_FALLBACK_ID = "system-sheet";
+
+/**
+ * Builds a sharer from a list of channels. This is the abstraction layer between the app
+ * and react-native-share / the OpenSDKs: the app only ever calls `sharer.share(id, payload)`
+ * and adds/removes channels by editing the `channels` array.
+ *
+ * Routing per share:
+ *   1. Emit `share_started`.
+ *   2. Unknown id, or `isAvailable()` false/throws → `share_unavailable`, route to fallback.
+ *   3. `share()` throws → `share_failed`, route to fallback.
+ *   4. Emit `share_completed` with the channel that actually handled it.
+ *
+ * The fallback (default: the channel registered as "system-sheet") is never used to route
+ * back into itself, so a missing/failed fallback yields a non-completed outcome instead of
+ * looping.
+ */
+export function createSharer(options: CreateSharerOptions): Sharer {
+  const { channels, onEvent } = options;
+
+  const registry = new Map<string, ShareChannel>();
+  for (const channel of channels) {
+    if (registry.has(channel.id)) {
+      throw new Error(`[rn-social-share] Duplicate channel id "${channel.id}"`);
+    }
+    registry.set(channel.id, channel);
+  }
+
+  const fallbackId = options.fallbackChannelId ?? DEFAULT_FALLBACK_ID;
+  const fallbackChannel = registry.get(fallbackId);
+
+  const emit = (event: ShareEvent): void => {
+    try {
+      onEvent?.(event);
+    } catch {
+      // Analytics/logging must never break a share.
+    }
+  };
+
+  const emitCompleted = (outcome: ShareOutcome): void => {
+    emit({
+      type: "share_completed",
+      channel: outcome.channel,
+      fellBack: outcome.fellBack ?? false,
+      targetApp: outcome.targetApp,
+    });
+  };
+
+  const runFallback = async (requestedId: string, payload: SharePayload): Promise<ShareOutcome> => {
+    if (!fallbackChannel || fallbackChannel.id === requestedId) {
+      return { completed: false, channel: requestedId, fellBack: false };
+    }
+    try {
+      const outcome = await fallbackChannel.share(payload);
+      return { ...outcome, channel: fallbackChannel.id, fellBack: true };
+    } catch {
+      return { completed: false, channel: fallbackChannel.id, fellBack: true };
+    }
+  };
+
+  const share = async (channelId: string, payload: SharePayload): Promise<ShareOutcome> => {
+    emit({ type: "share_started", channel: channelId, hasImage: Boolean(payload.imageUri) });
+
+    const channel = registry.get(channelId);
+
+    let available = channel !== undefined;
+    if (channel) {
+      try {
+        available = await channel.isAvailable(payload);
+      } catch {
+        available = false;
+      }
+    }
+
+    if (!channel || !available) {
+      emit({ type: "share_unavailable", channel: channelId });
+      const outcome = await runFallback(channelId, payload);
+      emitCompleted(outcome);
+      return outcome;
+    }
+
+    try {
+      const outcome = await channel.share(payload);
+      emitCompleted(outcome);
+      return outcome;
+    } catch (error) {
+      emit({ type: "share_failed", channel: channelId, error });
+      const outcome = await runFallback(channelId, payload);
+      emitCompleted(outcome);
+      return outcome;
+    }
+  };
+
+  return {
+    channelIds: channels.map((channel) => channel.id),
+    has: (channelId) => registry.has(channelId),
+    isAvailable: async (channelId, payload) => {
+      const channel = registry.get(channelId);
+      if (!channel) {
+        return false;
+      }
+      try {
+        return await channel.isAvailable(payload);
+      } catch {
+        return false;
+      }
+    },
+    share,
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Core (pure, no UI)
+export * from "./types";
+export { captureCardImage, type CaptureOptions } from "./capture";
+export { createSharer } from "./createSharer";
+
+// Channels (modular registry)
+export * from "./channels";
+
+// React layer (optional hooks + helpers)
+export * from "./react";

package/src/plugin/withSocialShare.js

@@ -0,0 +1,68 @@
+const { withInfoPlist, withAndroidManifest } = require("@expo/config-plugins");
+
+// The URL schemes a channel needs in the iOS Info.plist LSApplicationQueriesSchemes so
+// `Linking.canOpenURL()` (used by the channels' `isAvailable`) returns true instead of
+// always false.
+const IOS_QUERY_SCHEMES = {
+  instagram: ["instagram-stories", "instagram"],
+  whatsapp: ["whatsapp"],
+  tiktok: ["tiktoksharesdk", "snssdk1233", "musically"],
+};
+
+// The Android package names a channel needs in <queries> for package visibility
+// (Android 11+), so app detection / share targeting works.
+const ANDROID_PACKAGES = {
+  instagram: ["com.instagram.android"],
+  whatsapp: ["com.whatsapp"],
+  tiktok: ["com.zhiliaoapp.musically", "com.ss.android.ugc.trill"],
+};
+
+/**
+ * Expo config plugin that declares the app-query permissions the enabled share channels
+ * need, so channel availability detection works on both platforms.
+ *
+ * Usage in app.config.ts / app.json:
+ *   ["@rocapine/rn-social-share", { "channels": ["instagram", "whatsapp", "tiktok"] }]
+ *
+ * Scope note: this covers the query/visibility entries only. TikTok's full native wiring
+ * (client key in Info.plist / strings.xml, meta-data, and the FileProvider) is heavier and
+ * currently lives in the app's own `withTikTokShare` plugin; folding it in here is a
+ * follow-up once this package is validated with a prebuild.
+ */
+const withSocialShare = (config, options = {}) => {
+  const channels = Array.isArray(options.channels) ? options.channels : [];
+
+  config = withInfoPlist(config, (cfg) => {
+    const existing = cfg.modResults.LSApplicationQueriesSchemes || [];
+    const schemes = new Set(existing);
+    for (const channel of channels) {
+      for (const scheme of IOS_QUERY_SCHEMES[channel] || []) {
+        schemes.add(scheme);
+      }
+    }
+    cfg.modResults.LSApplicationQueriesSchemes = Array.from(schemes);
+    return cfg;
+  });
+
+  config = withAndroidManifest(config, (cfg) => {
+    const manifest = cfg.modResults.manifest;
+    manifest.queries = manifest.queries || [{}];
+    const query = manifest.queries[0];
+    query.package = query.package || [];
+    const seen = new Set(query.package.map((p) => p.$ && p.$["android:name"]));
+    for (const channel of channels) {
+      for (const pkg of ANDROID_PACKAGES[channel] || []) {
+        if (!seen.has(pkg)) {
+          query.package.push({ $: { "android:name": pkg } });
+          seen.add(pkg);
+        }
+      }
+    }
+    return cfg;
+  });
+
+  return config;
+};
+
+module.exports = withSocialShare;
+module.exports.default = withSocialShare;

package/src/react/imageReadiness.ts

@@ -0,0 +1,15 @@
+/**
+ * A shareable card often contains several asynchronously-loaded images (a fruit
+ * illustration, a logo…). view-shot must not capture until every one has painted, or an
+ * image that loads after the capture fires is absent from the file. This was ROC-2883: the
+ * capture only awaited one image, so the logo was frequently missing from the export.
+ *
+ * Track loaded keys in a Set as each `<Image onLoad>` fires, then gate the capture on
+ * `areAllImagesLoaded(loaded, REQUIRED_KEYS)`.
+ */
+export function areAllImagesLoaded(
+  loaded: ReadonlySet<string>,
+  required: readonly string[],
+): boolean {
+  return required.every((key) => loaded.has(key));
+}

package/src/react/index.ts

@@ -0,0 +1,9 @@
+export { useShareCard } from "./useShareCard";
+export { useScreenshotTrigger } from "./useScreenshotTrigger";
+export { areAllImagesLoaded } from "./imageReadiness";
+export {
+  SCREENSHOT_DEBOUNCE_MS,
+  shouldHandleScreenshot,
+  createScreenshotGate,
+  screenshotGate,
+} from "./screenshotDebounce";

package/src/react/screenshotDebounce.ts

@@ -0,0 +1,36 @@
+export const SCREENSHOT_DEBOUNCE_MS = 1000;
+
+export function shouldHandleScreenshot(
+  lastHandledAt: number | null,
+  now: number,
+  windowMs: number = SCREENSHOT_DEBOUNCE_MS,
+): boolean {
+  if (lastHandledAt === null) {
+    return true;
+  }
+  return now - lastHandledAt >= windowMs;
+}
+
+/**
+ * A screenshot is a single OS-wide event, but one screenshot can reach a handler more than
+ * once: iOS double-fires the notification, and release builds can mount more than one
+ * `useScreenshotTrigger` instance (ROC-2854). A per-instance debounce can't dedupe across
+ * instances. This gate holds the last-handled timestamp so that, no matter how many callers
+ * react to the same screenshot, `gate(now)` returns `true` at most once per `windowMs`.
+ *
+ * The hook uses a single shared gate (`screenshotGate`); the factory exists so tests (and
+ * apps that want isolation) get their own instance.
+ */
+export function createScreenshotGate(windowMs: number = SCREENSHOT_DEBOUNCE_MS) {
+  let lastHandledAt: number | null = null;
+  return function tryHandleScreenshot(now: number): boolean {
+    if (shouldHandleScreenshot(lastHandledAt, now, windowMs)) {
+      lastHandledAt = now;
+      return true;
+    }
+    return false;
+  };
+}
+
+/** Single app-wide screenshot gate shared by every `useScreenshotTrigger`. */
+export const screenshotGate = createScreenshotGate();

package/src/react/useScreenshotTrigger.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef } from "react";
+import { screenshotGate } from "./screenshotDebounce";
+
+/**
+ * Calls `onScreenshot` when the user takes a screenshot, while `enabled` is true — the
+ * "share on screenshot" trigger from the Expo Marathon pattern. Dedup is enforced by a
+ * shared, app-wide gate so one screenshot fires at most one handler even when iOS
+ * double-fires or several instances are mounted (ROC-2854).
+ *
+ * No-ops silently where screenshot detection is unavailable (iOS supported; Android only
+ * API 34+) or when `expo-screen-capture` isn't installed — the lazy require keeps that
+ * dependency optional, and an explicit share button remains the fallback.
+ */
+export function useScreenshotTrigger(enabled: boolean, onScreenshot: () => void): void {
+  const onScreenshotRef = useRef(onScreenshot);
+  onScreenshotRef.current = onScreenshot;
+
+  useEffect(
+    function subscribeToScreenshots() {
+      if (!enabled) {
+        return;
+      }
+      let subscription: { remove: () => void } | undefined;
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { addScreenshotListener } = require("expo-screen-capture");
+        subscription = addScreenshotListener(() => {
+          if (screenshotGate(Date.now())) {
+            onScreenshotRef.current();
+          }
+        });
+      } catch {
+        // Screenshot detection unavailable / module not installed — silent fail.
+      }
+      return () => subscription?.remove();
+    },
+    [enabled],
+  );
+}

package/src/react/useShareCard.ts

@@ -0,0 +1,26 @@
+import { useCallback, useRef } from "react";
+import type { View } from "react-native";
+import { captureCardImage, type CaptureOptions } from "../capture";
+
+/**
+ * Headless capture hook: gives you a `ref` to attach to your off-screen card view and a
+ * `capture()` that renders it to a branded image file (or `undefined` on failure).
+ *
+ * The card visual itself stays in the app — the package only captures whatever you point
+ * the ref at. Render the card off-screen (e.g. `position: "absolute", left: -10000`) and
+ * gate `capture()` on `areAllImagesLoaded` if the card has async images.
+ *
+ * Need two variants (e.g. rounded for the sheet, square full-bleed for Stories)? Call this
+ * hook twice, or call `captureCardImage` directly with each ref.
+ */
+export function useShareCard(options: CaptureOptions) {
+  const ref = useRef<View>(null);
+  const { fileName, width, height, format, quality, onError } = options;
+
+  const capture = useCallback(
+    () => captureCardImage(ref, { fileName, width, height, format, quality, onError }),
+    [fileName, width, height, format, quality, onError],
+  );
+
+  return { ref, capture };
+}

package/src/types.ts

@@ -0,0 +1,69 @@
+/**
+ * The data a share can carry. Every field is optional so a channel can pick what it
+ * understands: `copyLink` only needs `link`, `instagramStories` only needs `imageUri`,
+ * the system sheet uses all of them.
+ */
+export type SharePayload = {
+  /** Local file URI of the image to share (PNG). Produced by `captureCardImage`. */
+  imageUri?: string;
+  /** Text caption / body. */
+  message?: string;
+  /** A URL to share or copy. */
+  link?: string;
+  /** File name (no extension needed) the OS share sheet shows for the attachment. */
+  fileName?: string;
+};
+
+/** Result of a share attempt. Best-effort: some channels cannot know if the user completed. */
+export type ShareOutcome = {
+  /** Whether the flow was completed as far as we can tell (false = dismissed/denied). */
+  completed: boolean;
+  /** The channel id that ultimately handled the share (may differ from the requested one). */
+  channel: string;
+  /** True when the requested channel was unavailable/failed and we routed to the fallback. */
+  fellBack?: boolean;
+  /** For the system sheet: which app the OS reported handling the share, if any. */
+  targetApp?: string | null;
+  /** For `saveToLibrary`: the OS denied photo-library permission. */
+  permissionDenied?: boolean;
+};
+
+/**
+ * A single share destination. Implement this to add a new channel — that is the whole
+ * extension surface. Register instances with `createSharer({ channels: [...] })`.
+ */
+export type ShareChannel = {
+  /** Stable identifier, e.g. "instagram", "tiktok", "system-sheet". */
+  readonly id: string;
+  /** Can this channel currently handle the payload (app installed, image present…)? */
+  isAvailable(payload: SharePayload): Promise<boolean>;
+  /** Perform the share. Resolve with the outcome; throw only on unexpected errors. */
+  share(payload: SharePayload): Promise<ShareOutcome>;
+};
+
+/** Events emitted by the sharer so the host app can wire its own analytics/logging. */
+export type ShareEvent =
+  | { type: "share_started"; channel: string; hasImage: boolean }
+  | { type: "share_completed"; channel: string; fellBack: boolean; targetApp?: string | null }
+  | { type: "share_unavailable"; channel: string }
+  | { type: "share_failed"; channel: string; error: unknown };
+
+export type CreateSharerOptions = {
+  /** Ordered list of channels. Order is preserved in `channelIds` for building UIs. */
+  channels: ShareChannel[];
+  /**
+   * Channel id used when a requested channel is unavailable or throws.
+   * Defaults to "system-sheet" when a channel with that id is registered.
+   */
+  fallbackChannelId?: string;
+  /** Analytics / logging sink. Fire-and-forget — thrown errors here never break a share. */
+  onEvent?: (event: ShareEvent) => void;
+};
+
+export type Sharer = {
+  /** Registered channel ids in registration order (handy for rendering a channel row). */
+  readonly channelIds: string[];
+  has(channelId: string): boolean;
+  isAvailable(channelId: string, payload: SharePayload): Promise<boolean>;
+  share(channelId: string, payload: SharePayload): Promise<ShareOutcome>;
+};