@fias/arche-sdk 2.10.0 → 2.12.0

package/dist/index.mjs

@@ -714,6 +714,9 @@ var PLUGIN_DATASTORE_ENTITY_ID = "ent_intg_plugin_datastore_000000";
 var PLUGIN_WORKSPACES_ENTITY_ID = "ent_intg_plugin_workspaces_00000";
 var PLUGIN_STORE_ENTITY_ID = "ent_intg_plugin_store_0000000000";
 var VAULT_USER_DOCUMENTS_ENTITY_ID = "ent_intg_vault_documents_0000000";
+var COMMUNITY_ASSETS_ENTITY_ID = "ent_intg_community_assets_000000";
+var COMMUNITY_ASSET_MAX_URL_BATCH = 50;
+var COMMUNITY_ASSET_MAX_PUBLISH_BATCH = 20;
 async function invokeEntityOp(bridge, entityId, op, args = {}) {
   const res = await bridge.request("entity_invoke", {
     entityId,
@@ -930,42 +933,6 @@ function useImageEntities(filter) {
   }, [fetchOnce]);
   return { entities, isLoading, error, refetch: fetchOnce };
 }
-var BG_REMOVAL_MAX_BYTES = 25 * 1024 * 1024;
-var IMGLY_BACKGROUND_REMOVAL_ENTITY_ID = "ent_intg_imgly_bgrm_000000000000";
-function useBackgroundRemoval() {
-  const bridge = useBridge();
-  const [isLoading, setIsLoading] = useState2(false);
-  const [result, setResult] = useState2(null);
-  const [error, setError] = useState2(null);
-  const removeBackground = useCallback(
-    async (image) => {
-      if (image.size > BG_REMOVAL_MAX_BYTES) {
-        const e = new Error("background-removal: image exceeds 25 MiB limit");
-        setError(e);
-        throw e;
-      }
-      setIsLoading(true);
-      setError(null);
-      try {
-        const res = await bridge.request(
-          "client_entity_invoke",
-          { entityId: IMGLY_BACKGROUND_REMOVAL_ENTITY_ID, input: { image } },
-          12e4
-        );
-        setResult(res.image);
-        return res.image;
-      } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        setError(e);
-        throw e;
-      } finally {
-        setIsLoading(false);
-      }
-    },
-    [bridge]
-  );
-  return { removeBackground, isLoading, result, error };
-}
 var CLIENT_ENTITY_INVOKE_TIMEOUT_MS = 12e4;
 function useClientEntity() {
   const bridge = useBridge();
@@ -1223,7 +1190,8 @@ function useFiasDataStore() {
           userScope: options?.userScope ?? "user",
           searchable: options?.searchable,
           writeMinRole: options?.writeMinRole,
-          readMinRole: options?.readMinRole
+          readMinRole: options?.readMinRole,
+          writePolicy: options?.writePolicy
         }
       );
       return res.collection;
@@ -1271,6 +1239,23 @@ function useFiasDataStore() {
     },
     [bridge]
   );
+  const getDocument = useCallback(
+    async (collection, key, options) => {
+      const res = await invokeEntityOp(bridge, PLUGIN_DATASTORE_ENTITY_ID, "get", {
+        collection,
+        key,
+        workspaceId: options?.workspaceId
+      });
+      if (res.data === null || res.data === void 0) return null;
+      return {
+        key: res.key ?? key,
+        data: res.data,
+        updatedAt: res.updatedAt ?? "",
+        ...res.authoredByCollaborator !== void 0 ? { authoredByCollaborator: res.authoredByCollaborator } : {}
+      };
+    },
+    [bridge]
+  );
   const query = useCallback(
     async (collection, options, scope) => {
       return invokeEntityOp(bridge, PLUGIN_DATASTORE_ENTITY_ID, "query", {
@@ -1321,6 +1306,7 @@ function useFiasDataStore() {
       deleteCollection,
       put,
       get,
+      getDocument,
       query,
       search,
       delete: deleteDoc,
@@ -1332,6 +1318,7 @@ function useFiasDataStore() {
       deleteCollection,
       put,
       get,
+      getDocument,
       query,
       search,
       deleteDoc,
@@ -1874,6 +1861,179 @@ function useVaultUserDocuments() {
   );
   return useMemo2(() => ({ pick, list, get, getDownloadUrl }), [pick, list, get, getDownloadUrl]);
 }
+var COMMUNITY_ASSET_URL_REFRESH_BUFFER_MS = 3e4;
+var communityAssetUrlCache = /* @__PURE__ */ new Map();
+var communityAssetUrlInflight = /* @__PURE__ */ new Map();
+async function fetchCommunityAssetUrls(bridge, assetIds) {
+  const now = Date.now();
+  const hits = [];
+  const misses = [];
+  for (const assetId of assetIds) {
+    const cached = communityAssetUrlCache.get(assetId);
+    if (cached && now < cached.expiresAt - COMMUNITY_ASSET_URL_REFRESH_BUFFER_MS) {
+      hits.push(cached);
+    } else {
+      misses.push(assetId);
+    }
+  }
+  if (misses.length === 0) return hits;
+  const pending = [];
+  const toRequest = [];
+  for (const assetId of misses) {
+    const inflight = communityAssetUrlInflight.get(assetId);
+    if (inflight) pending.push(inflight);
+    else toRequest.push(assetId);
+  }
+  for (let i = 0; i < toRequest.length; i += COMMUNITY_ASSET_MAX_URL_BATCH) {
+    const chunk = toRequest.slice(i, i + COMMUNITY_ASSET_MAX_URL_BATCH);
+    const promise = invokeEntityOp(
+      bridge,
+      COMMUNITY_ASSETS_ENTITY_ID,
+      "get_urls",
+      { assetIds: chunk }
+    ).then((res) => {
+      for (const url of res.urls) {
+        communityAssetUrlCache.set(url.assetId, url);
+      }
+      return res.urls;
+    }).finally(() => {
+      for (const assetId of chunk) {
+        communityAssetUrlInflight.delete(assetId);
+      }
+    });
+    for (const assetId of chunk) {
+      communityAssetUrlInflight.set(assetId, promise);
+    }
+    pending.push(promise);
+  }
+  const settled = await Promise.all(pending);
+  const requested = new Set(assetIds);
+  const seen = new Set(hits.map((h) => h.assetId));
+  for (const batch of settled) {
+    for (const url of batch) {
+      if (!requested.has(url.assetId) || seen.has(url.assetId)) continue;
+      seen.add(url.assetId);
+      hits.push(url);
+    }
+  }
+  return hits;
+}
+function useCommunityAssets() {
+  const bridge = useBridge();
+  const publish = useCallback(
+    async (input) => {
+      const res = await invokeEntityOp(
+        bridge,
+        COMMUNITY_ASSETS_ENTITY_ID,
+        "publish",
+        {
+          fileId: input.fileId,
+          title: input.title,
+          caption: input.caption,
+          tags: input.tags,
+          clientRef: input.clientRef,
+          attributionName: input.attributionName
+        }
+      );
+      return res.asset;
+    },
+    [bridge]
+  );
+  const publishMany = useCallback(
+    async (items) => {
+      const results = [];
+      for (let i = 0; i < items.length; i += COMMUNITY_ASSET_MAX_PUBLISH_BATCH) {
+        const res = await invokeEntityOp(
+          bridge,
+          COMMUNITY_ASSETS_ENTITY_ID,
+          "publish_many",
+          { items: items.slice(i, i + COMMUNITY_ASSET_MAX_PUBLISH_BATCH) }
+        );
+        results.push(...res.results);
+      }
+      return results;
+    },
+    [bridge]
+  );
+  const unpublish = useCallback(
+    async (assetId) => {
+      const res = await invokeEntityOp(
+        bridge,
+        COMMUNITY_ASSETS_ENTITY_ID,
+        "unpublish",
+        { assetId }
+      );
+      communityAssetUrlCache.delete(assetId);
+      return res.asset;
+    },
+    [bridge]
+  );
+  const listMine = useCallback(
+    async (options) => invokeEntityOp(bridge, COMMUNITY_ASSETS_ENTITY_ID, "list_mine", {
+      limit: options?.limit,
+      cursor: options?.cursor
+    }),
+    [bridge]
+  );
+  const listCommunity = useCallback(
+    async (options) => invokeEntityOp(
+      bridge,
+      COMMUNITY_ASSETS_ENTITY_ID,
+      "list_community",
+      { limit: options?.limit, cursor: options?.cursor, tag: options?.tag }
+    ),
+    [bridge]
+  );
+  const get = useCallback(
+    async (assetId) => {
+      const res = await invokeEntityOp(
+        bridge,
+        COMMUNITY_ASSETS_ENTITY_ID,
+        "get",
+        { assetId }
+      );
+      return res.asset;
+    },
+    [bridge]
+  );
+  const getUrls = useCallback(
+    (assetIds) => fetchCommunityAssetUrls(bridge, assetIds),
+    [bridge]
+  );
+  const getUrl = useCallback(
+    async (assetId) => {
+      const [url] = await fetchCommunityAssetUrls(bridge, [assetId]);
+      if (!url) {
+        throw new Error(`Community asset ${assetId} is not available`);
+      }
+      return url;
+    },
+    [bridge]
+  );
+  const report = useCallback(
+    async (assetId, reason, details) => invokeEntityOp(
+      bridge,
+      COMMUNITY_ASSETS_ENTITY_ID,
+      "report",
+      { assetId, reason, details }
+    ),
+    [bridge]
+  );
+  return useMemo2(
+    () => ({
+      publish,
+      publishMany,
+      unpublish,
+      listMine,
+      listCommunity,
+      get,
+      getUrl,
+      getUrls,
+      report
+    }),
+    [publish, publishMany, unpublish, listMine, listCommunity, get, getUrl, getUrls, report]
+  );
+}
 
 // src/generated/surfaces.ts
 var AUDIO_AUDIO_ISOLATION_SURFACE_KEY = "audio.audio-isolation";
@@ -1941,6 +2101,8 @@ var useIntegrationWebSearch = () => useSurface(
 
 // src/generated/permissions.ts
 var VALID_PLUGIN_PERMISSIONS = [
+  "assets:community:publish",
+  "assets:community:read",
   "assets:read",
   "data:search",
   "data:store",
@@ -1949,7 +2111,6 @@ var VALID_PLUGIN_PERMISSIONS = [
   "entities:client_invoke",
   "entities:image_edit",
   "entities:image_generate",
-  "entities:image_remove_background",
   "entities:invoke",
   "entities:web_search",
   "navigation:open_arche",
@@ -1966,15 +2127,16 @@ function isValidPluginPermission(perm) {
   return VALID_PLUGIN_PERMISSIONS.includes(perm);
 }
 var PLUGIN_PERMISSION_DESCRIPTIONS = {
+  "assets:community:publish": "Share images you made here so other people using this app can see them, and manage what you have shared.",
+  "assets:community:read": "Show you images that other people using this app have shared. Everything shared is checked before anyone can see it.",
   "assets:read": "Show images from this app's published asset library.",
   "data:search": "Search this app's own data semantically \u2014 costs credits per search.",
   "data:store": "Save structured data in this app's own private database.",
   "data:workspace": "Create team workspaces and manage their members.",
   "entities:audio_generate": "Generate audio with platform AI \u2014 costs credits.",
-  "entities:client_invoke": "Use free on-device tools (grammar check, translation, background removal) in your browser.",
+  "entities:client_invoke": "Use free on-device tools (grammar check, translation) in your browser.",
   "entities:image_edit": "Edit images with platform AI \u2014 costs credits.",
   "entities:image_generate": "Generate images with platform AI \u2014 costs credits.",
-  "entities:image_remove_background": "Remove image backgrounds.",
   "entities:invoke": "Use platform AI (text) on your behalf \u2014 costs credits.",
   "entities:web_search": "Search the live web on your behalf \u2014 costs credits.",
   "navigation:open_arche": "Open other arches for you (navigation only).",
@@ -2020,7 +2182,12 @@ var fias = {
         getBridge(),
         PLUGIN_DATASTORE_ENTITY_ID,
         "create_collection",
-        { name, userScope: options?.userScope ?? "user", searchable: options?.searchable }
+        {
+          name,
+          userScope: options?.userScope ?? "user",
+          searchable: options?.searchable,
+          writePolicy: options?.writePolicy
+        }
       );
       return res.collection;
     },
@@ -2051,6 +2218,18 @@ var fias = {
       );
       return res.data;
     },
+    /** Like get(), but returns the full envelope incl. the shared-scope
+     *  `authoredByCollaborator` trust signal. */
+    async getDocument(collection, key) {
+      const res = await invokeEntityOp(getBridge(), PLUGIN_DATASTORE_ENTITY_ID, "get", { collection, key });
+      if (res.data === null || res.data === void 0) return null;
+      return {
+        key: res.key ?? key,
+        data: res.data,
+        updatedAt: res.updatedAt ?? "",
+        ...res.authoredByCollaborator !== void 0 ? { authoredByCollaborator: res.authoredByCollaborator } : {}
+      };
+    },
     async query(collection, options) {
       return invokeEntityOp(
         getBridge(),
@@ -4082,8 +4261,8 @@ export {
   resetBridge,
   useArcheAssets,
   useAudioGeneration,
-  useBackgroundRemoval,
   useClientEntity,
+  useCommunityAssets,
   useDataSubscription,
   useElevenLabsAudioIsolation,
   useElevenLabsForcedAlignment,

package/dist/types.d.ts

@@ -342,27 +342,6 @@ export interface ImageGenerationApi {
     result: ImageGenerationResult | null;
     error: Error | null;
 }
-/**
- * Result of background removal via the `client_entity_invoke` bridge op
- * targeting the imgly background-removal entity. A transparent PNG.
- *
- * The blob is processed entirely in the host page using a WASM/ONNX model —
- * bytes never leave the user's device. Inputs are capped at 25 MiB
- * (26,214,400 bytes); larger inputs reject with an error.
- */
-export interface ImageRemoveBackgroundResult {
-    image: Blob;
-}
-/**
- * Background removal API available via useBackgroundRemoval() hook.
- */
-export interface BackgroundRemovalApi {
-    removeBackground: (image: Blob) => Promise<Blob>;
-    isLoading: boolean;
-    /** The Blob returned by the most recent successful call, or null. */
-    result: Blob | null;
-    error: Error | null;
-}
 /**
  * Parameters for on-device translation via the `client_entity_invoke` bridge
  * op targeting the NLLB-200 translation entity.
@@ -847,6 +826,143 @@ export interface ArcheAssetsApi {
     /** Refresh the signed URL for a single asset. */
     getUrl: (assetId: string) => Promise<ArcheAsset>;
 }
+/** Where an asset sits in the moderation lifecycle, from the author's view. */
+export type CommunityAssetStatus = 
+/** Awaiting a verdict. Nobody else can see it yet. */
+'pending_moderation'
+/** Live — every user of this arche can see it. */
+ | 'published'
+/** Moderation said no. Terminal; `moderationReason` says roughly why. */
+ | 'rejected'
+/** Held for a human moderator. */
+ | 'needs_review'
+/** The author removed it. */
+ | 'unpublished'
+/** An admin removed it. */
+ | 'taken_down';
+export interface CommunityAsset {
+    assetId: string;
+    archeId: string;
+    title: string | null;
+    caption: string | null;
+    tags: string[];
+    /** Opt-in display credit chosen by the publisher; null when anonymous. */
+    attributionName: string | null;
+    /** Always `image/png` — publishing normalizes to a canonical PNG. */
+    contentType: string;
+    sizeBytes: number;
+    /** ISO timestamp, or null while it is not published. */
+    publishedAt: string | null;
+    /** Present only on YOUR OWN assets (`listMine`, and `get` when you published it). */
+    status?: CommunityAssetStatus;
+    /** Coarse reason a rejected asset was refused. Own assets only. */
+    moderationReason?: string | null;
+    /** Whatever `clientRef` you passed at publish time. Own assets only. */
+    clientRef?: string | null;
+    createdAt?: string;
+}
+/** A short-lived signed URL for one published asset. Render with `<img src>`. */
+export interface CommunityAssetUrl {
+    assetId: string;
+    url: string;
+    /**
+     * Epoch MILLISECONDS (the Vault convention — note `ArcheAsset.expiresAt`
+     * above is unix SECONDS). URLs last ~5 minutes; the hook refreshes them for
+     * you, so prefer calling `getUrls` again over caching this yourself.
+     */
+    expiresAt: number;
+}
+export interface CommunityAssetPublishInput {
+    /**
+     * The `fileId` from a `useImageGeneration()` result — the image must be one
+     * YOU created or uploaded, in your own Fias files.
+     *
+     * Required here, while `ImageGenerationResult.fileId` is OPTIONAL (it is
+     * absent if the generated image was never written to the user's files). That
+     * mismatch is deliberate: TypeScript makes you handle the missing case rather
+     * than forwarding `undefined` and discovering it as a runtime
+     * `FILE_NOT_FOUND`. Guard before publishing:
+     *
+     * ```ts
+     * const image = await generate({ prompt });
+     * if (!image.fileId) return;  // nothing saved — nothing to publish
+     * await publish({ fileId: image.fileId });
+     * ```
+     */
+    fileId: string;
+    title?: string | null;
+    caption?: string | null;
+    /** Up to 16, each ≤64 chars. The only filterable dimension in `listCommunity`. */
+    tags?: string[];
+    /** Your own correlation handle (e.g. `"page-3"`), echoed back per item. */
+    clientRef?: string | null;
+    /** Opt-in display credit. Screened like every other author-supplied string. */
+    attributionName?: string | null;
+}
+/**
+ * One item's outcome from `publishMany`. Items succeed or fail INDEPENDENTLY —
+ * a single rejected page must not sink a whole book — and retrying only the
+ * failures is safe: publishing the same bytes twice returns the first result
+ * rather than creating a duplicate.
+ */
+export type CommunityAssetPublishResult = {
+    clientRef: string | null;
+    asset: CommunityAsset;
+    error?: undefined;
+} | {
+    clientRef: string | null;
+    asset?: undefined;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface CommunityAssetListOptions {
+    /** 1..100. Default 30. */
+    limit?: number;
+    /** `nextCursor` from the previous page. */
+    cursor?: string | null;
+    /** Return only assets carrying this tag. `listCommunity` only. */
+    tag?: string | null;
+}
+export interface CommunityAssetListResult {
+    assets: CommunityAsset[];
+    /** Null when there are no more pages. */
+    nextCursor: string | null;
+}
+export type CommunityAssetReportReason = 'sexual' | 'violence' | 'hate' | 'illegal' | 'copyright' | 'spam' | 'other';
+export interface CommunityAssetsApi {
+    /**
+     * Publish one image you created so other users of this arche can see it.
+     * Free. It becomes visible only after moderation — expect
+     * `status: 'pending_moderation'` back, not `'published'`.
+     */
+    publish: (input: CommunityAssetPublishInput) => Promise<CommunityAsset>;
+    /** Publish up to 20 at once; each item succeeds or fails on its own. */
+    publishMany: (items: CommunityAssetPublishInput[]) => Promise<CommunityAssetPublishResult[]>;
+    /** Remove one of YOUR published assets. */
+    unpublish: (assetId: string) => Promise<CommunityAsset>;
+    /** Your own publications here, including moderation status. */
+    listMine: (options?: CommunityAssetListOptions) => Promise<CommunityAssetListResult>;
+    /** Browse what this arche's community has published. */
+    listCommunity: (options?: CommunityAssetListOptions) => Promise<CommunityAssetListResult>;
+    /** Metadata for one asset. */
+    get: (assetId: string) => Promise<CommunityAsset>;
+    /** A signed URL for one asset. Cached and auto-refreshed by the hook. */
+    getUrl: (assetId: string) => Promise<CommunityAssetUrl>;
+    /**
+     * Signed URLs for up to 50 assets in ONE call. Use this for a gallery or a
+     * multi-page book — 13 separate `getUrl` calls against a 5-minute TTL is the
+     * shape this exists to avoid. Ids that are gone or not yet published are
+     * simply omitted from the result rather than throwing.
+     */
+    getUrls: (assetIds: string[]) => Promise<CommunityAssetUrl[]>;
+    /** Report a published asset for moderator review. */
+    report: (assetId: string, reason: CommunityAssetReportReason, details?: string) => Promise<{
+        reportId: string;
+        status: string;
+    }>;
+}
 /**
  * Message types sent from the plugin iframe to the parent frame.
  */
@@ -1005,8 +1121,28 @@ export interface DataStoreCollection {
     /** Min workspace role to write / read (workspace-scoped only); null = default. */
     writeMinRole?: WorkspaceRole | null;
     readMinRole?: WorkspaceRole | null;
+    /** Who may write (shared-scoped only): see {@link DataStoreWritePolicy}. */
+    writePolicy?: DataStoreWritePolicy;
     createdAt: string;
 }
+/**
+ * Write policy for a `shared`-scope collection. Shared collections are
+ * read-by-all; the write policy narrows who may WRITE:
+ *
+ *   - 'any' (default): every user of the arche may write any document.
+ *   - 'author': creating a NEW key is open to everyone, but overwriting or
+ *     deleting an existing document requires being its author (the last
+ *     successful writer) or an arche collaborator. Use for shared catalogs /
+ *     caches where users publish their own entries.
+ *   - 'collaborators': only arche collaborators (owner/publisher) may write.
+ *     Use for curated content like a category taxonomy.
+ *
+ * Tighten-only after creation: re-declaring a STRICTER policy on an existing
+ * collection upgrades it when the caller is a collaborator (and is silently
+ * kept as-is for other users, so a shipped `ensure` call stays safe), while
+ * loosening is refused.
+ */
+export type DataStoreWritePolicy = 'any' | 'author' | 'collaborators';
 /**
  * A document returned from the data store.
  */
@@ -1014,6 +1150,15 @@ export interface DataStoreDocument<T = Record<string, unknown>> {
     key: string;
     data: T;
     updatedAt: string;
+    /**
+     * Present on SHARED-scope documents only: whether the document's last writer
+     * is an active arche collaborator (owner/publisher). The trust signal for
+     * shared content — e.g. refuse to feed a document into an AI prompt unless
+     * it was authored by a collaborator. The raw author identity is never
+     * exposed. Requires a platform/SDK version with write-policy support;
+     * absent otherwise.
+     */
+    authoredByCollaborator?: boolean;
 }
 /**
  * Filter condition for querying documents.
@@ -1069,6 +1214,8 @@ export interface DataStoreSearchMatch<T = Record<string, unknown>> {
     data: T;
     /** Cosine similarity in [0, 1]; higher is closer. */
     similarity: number;
+    /** Present on shared-scope matches: see {@link DataStoreDocument.authoredByCollaborator}. */
+    authoredByCollaborator?: boolean;
 }
 /**
  * Data Store API available via useFiasDataStore() hook.
@@ -1096,6 +1243,8 @@ export interface FiasDataStoreApi {
          *  collection above the default (write ≥ member, read ≥ viewer). */
         writeMinRole?: WorkspaceRole;
         readMinRole?: WorkspaceRole;
+        /** Shared-scoped only: who may write. See {@link DataStoreWritePolicy}. */
+        writePolicy?: DataStoreWritePolicy;
     }) => Promise<DataStoreCollection>;
     /** List all collections for this arche. */
     listCollections: () => Promise<DataStoreCollection[]>;
@@ -1110,6 +1259,14 @@ export interface FiasDataStoreApi {
     /** Get a document by key. Returns null if not found. Pass `{ workspaceId }`
      *  for a workspace-scoped collection. */
     get: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, options?: DataStoreScopeOptions) => Promise<T | null>;
+    /**
+     * Like {@link get}, but returns the full document envelope — key,
+     * `updatedAt`, and (for shared-scope documents) the
+     * {@link DataStoreDocument.authoredByCollaborator} trust signal — instead of
+     * the bare data. Use when the caller needs provenance, e.g. before feeding
+     * shared content into an AI prompt.
+     */
+    getDocument: <T extends Record<string, unknown> = Record<string, unknown>>(collection: string, key: string, options?: DataStoreScopeOptions) => Promise<DataStoreDocument<T> | null>;
     /** Query documents with filters, sorting, and pagination. For a
      *  `workspace`-scoped collection pass `scope: { workspaceId }`; the caller must
      *  be an active member (any role can read). */