expo-app-intents 0.4.7 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- Add `donateIntentAsync()` and `deleteDonationsAsync()` to donate App Intents to the system. ([#50760](https://github.com/expo/expo/pull/50760) by [@chrfalch](https://github.com/chrfalch))
+
+### Patch Changes
+
+- Updated dependencies. ([#50881](https://github.com/expo/expo/pull/50881), [#49933](https://github.com/expo/expo/pull/49933))
+  - @expo/ui@58.0.11
+
+## 0.4.8
+
+### Patch Changes
+
+- Updated dependencies. ([#50801](https://github.com/expo/expo/pull/50801), [#49986](https://github.com/expo/expo/pull/49986), [#50674](https://github.com/expo/expo/pull/50674), [#50786](https://github.com/expo/expo/pull/50786), [#50851](https://github.com/expo/expo/pull/50851))
+  - @expo/ui@58.0.10
+
 ## 0.4.7
 
 ### Patch Changes

package/README.md

@@ -45,6 +45,33 @@ export function AppIntentHandler() {
 }
 ```
 
+## Donating intents
+
+Donate an intent when the user performs its action inside your app, so the system can suggest it later on the Lock Screen, in Siri Suggestions, and in Spotlight. Make the intent donatable in Swift and register it in the `OnCreate` of your `AppIntentsSetup` module. JavaScript donates by the registered name. Nothing requires it to match the name the intent dispatches, but reusing that name gives each intent one name in JavaScript. The params that JavaScript passes are converted to the intent's `DonationParams` record, so a missing required field or a field of the wrong type rejects the donation. An intent without params only needs to conform to `DonatableAppIntent`. Declare the record with `@Field` properties, because the `@Record` macro is not available in the app target:
+
+```swift
+extension SaveNoteIntent: DonatableAppIntent {
+  struct DonationParams: Record {
+    @Field(.required) var text: String = ""
+  }
+
+  init(donationParams: DonationParams) {
+    self.init()
+    self.text = donationParams.text
+  }
+}
+
+AppIntentDonationRegistry.shared.register("saveNote", as: SaveNoteIntent.self)
+```
+
+Then donate it from JavaScript, and delete donations when they no longer apply:
+
+```ts
+await AppIntents.donateIntentAsync('saveNote', { text: 'Buy milk' });
+
+await AppIntents.deleteDonationsAsync({ intent: 'saveNote' });
+```
+
 ## Limitations
 
 - Shortcut phrases are compiled at build time and cannot be created from JavaScript at runtime. Only parameter values are dynamic.

package/build/ExpoAppIntents.types.d.ts

@@ -77,6 +77,31 @@ export type AppEntityIdentifierModifier = ModifierConfig & {
     /** Stable entity id from the matching App Intents entity catalog. */
     id: string;
 };
+/**
+ * A value that can be passed as an App Intent parameter: anything JSON can represent.
+ */
+export type AppIntentJSONValue = string | number | boolean | null | AppIntentJSONValue[] | {
+    [key: string]: AppIntentJSONValue;
+};
+/**
+ * Selects the donations that `deleteDonationsAsync()` deletes. Pass one of these shapes:
+ *
+ * - `{ ids }` deletes the donations with the given IDs, as returned by `donateIntentAsync()`.
+ * - `{ intent }` deletes every donation of the intent type registered under that name. When
+ *   several names are registered for one intent type, this also deletes the donations made under
+ *   the other names.
+ * - `{ entity, id }` deletes every donation that refers to the given entity. The `entity` value
+ *   must be registered with `AppEntityIdentifierRegistry.shared.register(_:as:)` or
+ *   `AppEntityIdentifierRegistry.shared.registerIndexed(_:as:)`.
+ */
+export type AppIntentDonationFilter = {
+    ids: string[];
+} | {
+    intent: string;
+} | {
+    entity: string;
+    id: string;
+};
 export type ExpoAppIntentsModuleEvents = {
     onIntent: (invocation: AppIntentInvocation) => void;
 };

package/build/ExpoAppIntents.types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["ExpoAppIntents.types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wBAAwB;AAwFxB,WAEE"}
+{"version":3,"sources":["ExpoAppIntents.types.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wBAAwB;AAmHxB,WAEE"}

package/build/ExpoAppIntentsModule.d.ts

@@ -1,5 +1,5 @@
 import { NativeModule } from 'expo-modules-core';
-import type { AppIntentEntity, AppIntentInvocation, ExpoAppIntentsModuleEvents } from './ExpoAppIntents.types';
+import type { AppIntentDonationFilter, AppIntentEntity, AppIntentInvocation, AppIntentJSONValue, ExpoAppIntentsModuleEvents } from './ExpoAppIntents.types';
 declare class ExpoAppIntentsNativeModule extends NativeModule<ExpoAppIntentsModuleEvents> {
     getPendingInvocationsAsync(): Promise<AppIntentInvocation[]>;
     removePendingInvocationAsync(id: string): Promise<void>;
@@ -8,6 +8,8 @@ declare class ExpoAppIntentsNativeModule extends NativeModule<ExpoAppIntentsModu
     reindexEntitiesAsync(kind: string | null): Promise<void>;
     getEntityCatalogAsync(kind: string): Promise<AppIntentEntity[]>;
     refreshShortcutsAsync(): Promise<void>;
+    donateIntentAsync(name: string, params?: Record<string, AppIntentJSONValue>): Promise<string>;
+    deleteDonationsAsync(filter: AppIntentDonationFilter): Promise<string[]>;
 }
 declare const _default: ExpoAppIntentsNativeModule | null;
 export default _default;

package/build/ExpoAppIntentsModule.js.map

@@ -1 +1 @@
-{"version":3,"sources":["ExpoAppIntentsModule.ts"],"sourcesContent":[null],"names":["NativeModule","requireOptionalNativeModule"],"mappings":"AAAA,SAASA,YAAY,EAAEC,2BAA2B,QAAQ,oBAAoB;AAkB9E,eAAeA,4BAAwD,kBAAkB"}
+{"version":3,"sources":["ExpoAppIntentsModule.ts"],"sourcesContent":[null],"names":["NativeModule","requireOptionalNativeModule"],"mappings":"AAAA,SAASA,YAAY,EAAEC,2BAA2B,QAAQ,oBAAoB;AAsB9E,eAAeA,4BAAwD,kBAAkB"}

package/build/index.d.ts

@@ -1,5 +1,5 @@
 import { type EventSubscription } from 'expo-modules-core';
-import type { AppEntityIdentifierModifier, AppIntentEntity, AppIntentInvocation, AppIntentsHandler } from './ExpoAppIntents.types';
+import type { AppEntityIdentifierModifier, AppIntentDonationFilter, AppIntentEntity, AppIntentInvocation, AppIntentJSONValue, AppIntentsHandler } from './ExpoAppIntents.types';
 export type * from './ExpoAppIntents.types';
 export { default as AppEntityView } from './AppEntityView';
 export type { AppEntityViewProps } from './AppEntityView.types';
@@ -112,6 +112,46 @@ export declare function getEntityCatalogAsync(kind: string): Promise<AppIntentEn
  * shortcuts.
  */
 export declare function refreshShortcutsAsync(): Promise<void>;
+/**
+ * Tells the system that the user just performed an App Intent's action in your app, for example
+ * ordering food from a screen rather than through Siri. The system learns from donations and can
+ * suggest the action later on the Lock Screen, in Siri Suggestions, and in Spotlight.
+ *
+ * The `name` must be registered from app-target Swift with
+ * `AppIntentDonationRegistry.shared.register(_:as:)`, on an intent that conforms to
+ * `DonatableAppIntent`. Native code converts `params` to the `DonationParams` record of that intent,
+ * and the intent builds itself from the record in its `init(donationParams:)`.
+ *
+ * The returned promise is fulfilled with an ID for the donation, which
+ * [`deleteDonationsAsync()`](#appintentsdeletedonationsasyncfilter) accepts, or with `null` when
+ * App Intents are unavailable. It is rejected when no intent is registered as `name`, when `params`
+ * misses a required field of the record or has a field of the wrong type, when the intent cannot be
+ * built from the record, or when the system fails to record the donation.
+ *
+ * > **Note:** The ID is the system's donation identifier in its encoded form. Store it only for as
+ * > long as you need it. An iOS update may change how the system encodes identifiers, and an ID
+ * > stored before such an update may then be rejected. To delete donations without stored IDs,
+ * > delete by `intent` or by `entity`.
+ *
+ * @platform ios
+ */
+export declare function donateIntentAsync(name: string, params?: Record<string, AppIntentJSONValue>): Promise<string | null>;
+/**
+ * Deletes donations made with [`donateIntentAsync()`](#appintentsdonateintentasyncname-params), so
+ * the system stops suggesting them. Delete donations when what they refer to is gone, for example
+ * after the user deletes an order, or when the user signs out.
+ *
+ * The returned promise is fulfilled with the IDs of the deleted donations, or with an empty array
+ * when App Intents are unavailable. It is rejected when `filter` names an intent or entity that is
+ * not registered, contains an ID that cannot be read, or contains an entity `id` that cannot be
+ * converted to the ID type of that entity. In those cases nothing is deleted. With `ids`, every ID
+ * is attempted. When the system fails to delete one or more of them, the promise is rejected with
+ * an error that lists the deleted IDs and the IDs that were not deleted. With `intent` or
+ * `entity`, the promise is rejected with the system error when the system fails to delete.
+ *
+ * @platform ios
+ */
+export declare function deleteDonationsAsync(filter: AppIntentDonationFilter): Promise<string[]>;
 /**
  * Returns an ExpoUI SwiftUI modifier config that ties a view to an AppEntity identifier.
  *

package/build/index.js

@@ -217,6 +217,54 @@ function callAppIntentsHandler(handler, pendingIntents, newIntent) {
     }
     return ExpoAppIntents.refreshShortcutsAsync();
 }
+/**
+ * Tells the system that the user just performed an App Intent's action in your app, for example
+ * ordering food from a screen rather than through Siri. The system learns from donations and can
+ * suggest the action later on the Lock Screen, in Siri Suggestions, and in Spotlight.
+ *
+ * The `name` must be registered from app-target Swift with
+ * `AppIntentDonationRegistry.shared.register(_:as:)`, on an intent that conforms to
+ * `DonatableAppIntent`. Native code converts `params` to the `DonationParams` record of that intent,
+ * and the intent builds itself from the record in its `init(donationParams:)`.
+ *
+ * The returned promise is fulfilled with an ID for the donation, which
+ * [`deleteDonationsAsync()`](#appintentsdeletedonationsasyncfilter) accepts, or with `null` when
+ * App Intents are unavailable. It is rejected when no intent is registered as `name`, when `params`
+ * misses a required field of the record or has a field of the wrong type, when the intent cannot be
+ * built from the record, or when the system fails to record the donation.
+ *
+ * > **Note:** The ID is the system's donation identifier in its encoded form. Store it only for as
+ * > long as you need it. An iOS update may change how the system encodes identifiers, and an ID
+ * > stored before such an update may then be rejected. To delete donations without stored IDs,
+ * > delete by `intent` or by `entity`.
+ *
+ * @platform ios
+ */ export async function donateIntentAsync(name, params) {
+    if (!ExpoAppIntents) {
+        return null;
+    }
+    return ExpoAppIntents.donateIntentAsync(name, params);
+}
+/**
+ * Deletes donations made with [`donateIntentAsync()`](#appintentsdonateintentasyncname-params), so
+ * the system stops suggesting them. Delete donations when what they refer to is gone, for example
+ * after the user deletes an order, or when the user signs out.
+ *
+ * The returned promise is fulfilled with the IDs of the deleted donations, or with an empty array
+ * when App Intents are unavailable. It is rejected when `filter` names an intent or entity that is
+ * not registered, contains an ID that cannot be read, or contains an entity `id` that cannot be
+ * converted to the ID type of that entity. In those cases nothing is deleted. With `ids`, every ID
+ * is attempted. When the system fails to delete one or more of them, the promise is rejected with
+ * an error that lists the deleted IDs and the IDs that were not deleted. With `intent` or
+ * `entity`, the promise is rejected with the system error when the system fails to delete.
+ *
+ * @platform ios
+ */ export async function deleteDonationsAsync(filter) {
+    if (!ExpoAppIntents) {
+        return [];
+    }
+    return ExpoAppIntents.deleteDonationsAsync(filter);
+}
 /**
  * Returns an ExpoUI SwiftUI modifier config that ties a view to an AppEntity identifier.
  *

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["index.ts"],"sourcesContent":[null],"names":["UnavailabilityError","useEffect","useRef","ExpoAppIntents","default","AppEntityView","MAX_SEEN_INVOCATION_IDS","isAvailable","addAppIntentListener","listener","remove","addListener","callAppIntentsHandler","handler","pendingIntents","newIntent","Promise","resolve","then","catch","error","console","warn","useAppIntents","handlerRef","current","isMounted","seenLiveInvocationIds","Set","deliveryQueue","enqueue","deliver","notify","deliverNewIntent","getPendingInvocationsAsync","length","deliverInitialPendingIntents","initialPendingIntents","filter","invocation","has","id","forEach","add","subscription","size","delete","values","next","value","removePendingInvocationAsync","clearPendingInvocationsAsync","setEntityCatalogAsync","kind","entities","reindexEntitiesAsync","getEntityCatalogAsync","refreshShortcutsAsync","appEntityIdentifier","entity","$type"],"mappings":"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"}
+{"version":3,"sources":["index.ts"],"sourcesContent":[null],"names":["UnavailabilityError","useEffect","useRef","ExpoAppIntents","default","AppEntityView","MAX_SEEN_INVOCATION_IDS","isAvailable","addAppIntentListener","listener","remove","addListener","callAppIntentsHandler","handler","pendingIntents","newIntent","Promise","resolve","then","catch","error","console","warn","useAppIntents","handlerRef","current","isMounted","seenLiveInvocationIds","Set","deliveryQueue","enqueue","deliver","notify","deliverNewIntent","getPendingInvocationsAsync","length","deliverInitialPendingIntents","initialPendingIntents","filter","invocation","has","id","forEach","add","subscription","size","delete","values","next","value","removePendingInvocationAsync","clearPendingInvocationsAsync","setEntityCatalogAsync","kind","entities","reindexEntitiesAsync","getEntityCatalogAsync","refreshShortcutsAsync","donateIntentAsync","name","params","deleteDonationsAsync","appEntityIdentifier","entity","$type"],"mappings":"AAAA,SAAiCA,mBAAmB,QAAQ,oBAAoB;AAChF,SAASC,SAAS,EAAEC,MAAM,QAAQ,QAAQ;AAU1C,OAAOC,oBAAoB,yBAAyB;AAGpD,SAASC,WAAWC,aAAa,QAAQ,kBAAkB;AAG3D,MAAMC,0BAA0B;AAEhC;;;CAGC,GACD,OAAO,SAASC;IACd,OAAOJ,kBAAkB;AAC3B;AAEA;;;;;;CAMC,GACD,OAAO,SAASK,qBACdC,QAAmD;IAEnD,IAAI,CAACN,gBAAgB;QACnB,OAAO;YAAEO,WAAU;QAAE;IACvB;IACA,OAAOP,eAAeQ,WAAW,CAAC,YAAYF;AAChD;AAEA,SAASG,sBACPC,OAA0B,EAC1BC,cAAqC,EACrCC,SAAqC;IAErC,OAAOC,QAAQC,OAAO,GACnBC,IAAI,CAAC,IAAML,QAAQC,gBAAgBC,YACnCI,KAAK,CAAC,CAACC;QACNC,QAAQC,IAAI,CAAC,6CAA6CF;IAC5D;AACJ;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASG,cAAcV,OAA0B;IACtD,MAAMW,aAAatB,OAAOW;IAE1BZ,UAAU;QACRuB,WAAWC,OAAO,GAAGZ;IACvB,GAAG;QAACA;KAAQ;IAEZZ,UAAU;QACR,IAAIyB,YAAY;QAChB,MAAMC,wBAAwB,IAAIC;QAClC,IAAIC,gBAA+Bb,QAAQC,OAAO;QAClD,MAAMa,UAAU,CAACC;YACfF,gBAAgBA,cAAcX,IAAI,CAACa;QACrC;QAEA,MAAMC,SAAS,CACblB,gBACAC;YAEA,IAAI,CAACW,WAAW;gBACd;YACF;YACA,OAAOd,sBAAsBY,WAAWC,OAAO,EAAEX,gBAAgBC;QACnE;QAEA,MAAMkB,mBAAmB,OAAOlB;YAC9B,IAAI;gBACF,MAAMD,iBAAiB,MAAMoB;gBAC7B,MAAMF,OAAOlB,eAAeqB,MAAM,GAAG,IAAIrB,iBAAiB;oBAACC;iBAAU,EAAEA;YACzE,EAAE,OAAOK,OAAO;gBACd,IAAIM,WAAW;oBACbL,QAAQD,KAAK,CAAC,mDAAmDA;oBACjE,MAAMY,OAAO;wBAACjB;qBAAU,EAAEA;gBAC5B;YACF;QACF;QAEA,MAAMqB,+BAA+B;YACnC,IAAI;gBACF,MAAMtB,iBAAiB,MAAMoB;gBAC7B,MAAMG,wBAAwBvB,eAAewB,MAAM,CACjD,CAACC,aAAe,CAACZ,sBAAsBa,GAAG,CAACD,WAAWE,EAAE;gBAE1DJ,sBAAsBK,OAAO,CAAC,CAAC,EAAED,EAAE,EAAE,GAAKd,sBAAsBgB,GAAG,CAACF;gBACpE,MAAMT,OAAOK,uBAAuB;YACtC,EAAE,OAAOjB,OAAO;gBACd,IAAIM,WAAW;oBACbL,QAAQD,KAAK,CAAC,mDAAmDA;oBACjE,MAAMY,OAAO,EAAE,EAAE;gBACnB;YACF;QACF;QAEA,wFAAwF;QACxF,8CAA8C;QAC9C,MAAMY,eAAepC,qBAAqB,CAACO;YACzC,IAAIY,sBAAsBa,GAAG,CAACzB,UAAU0B,EAAE,GAAG;gBAC3C;YACF;YACAd,sBAAsBgB,GAAG,CAAC5B,UAAU0B,EAAE;YACtC,IAAId,sBAAsBkB,IAAI,GAAGvC,yBAAyB;gBACxDqB,sBAAsBmB,MAAM,CAACnB,sBAAsBoB,MAAM,GAAGC,IAAI,GAAGC,KAAK;YAC1E;YACAnB,QAAQ,IAAMG,iBAAiBlB;QACjC;QAEAe,QAAQ,IAAMM;QAEd,OAAO;YACLV,YAAY;YACZkB,aAAalC,MAAM;QACrB;IACF,GAAG,EAAE;AACP;AAEA;;;;;;;;;;CAUC,GACD,OAAO,eAAewB;IACpB,IAAI,CAAC/B,gBAAgB;QACnB,OAAO,EAAE;IACX;IACA,OAAOA,eAAe+B,0BAA0B;AAClD;AAEA;;;;;;;CAOC,GACD,OAAO,eAAegB,6BAA6BT,EAAU;IAC3D,IAAI,CAACtC,gBAAgB;QACnB;IACF;IACA,OAAOA,eAAe+C,4BAA4B,CAACT;AACrD;AAEA;;;CAGC,GACD,OAAO,eAAeU;IACpB,IAAI,CAAChD,gBAAgB;QACnB;IACF;IACA,OAAOA,eAAegD,4BAA4B;AACpD;AAEA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,eAAeC,sBACpBC,IAAY,EACZC,QAA2B;IAE3B,IAAI,CAACnD,gBAAgB;QACnB;IACF;IACA,OAAOA,eAAeiD,qBAAqB,CAACC,MAAMC;AACpD;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,eAAeC,qBAAqBF,IAAa;IACtD,IAAI,CAAClD,gBAAgB;QACnB;IACF;IACA,OAAOA,eAAeoD,oBAAoB,CAACF,QAAQ;AACrD;AAEA;;;;;;CAMC,GACD,OAAO,eAAeG,sBAAsBH,IAAY;IACtD,IAAI,CAAClD,gBAAgB;QACnB,OAAO,EAAE;IACX;IACA,OAAOA,eAAeqD,qBAAqB,CAACH;AAC9C;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeI;IACpB,IAAI,CAACtD,gBAAgB;QACnB,MAAM,IAAIH,oBAAoB,oBAAoB;IACpD;IACA,OAAOG,eAAesD,qBAAqB;AAC7C;AAEA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,eAAeC,kBACpBC,IAAY,EACZC,MAA2C;IAE3C,IAAI,CAACzD,gBAAgB;QACnB,OAAO;IACT;IACA,OAAOA,eAAeuD,iBAAiB,CAACC,MAAMC;AAChD;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,eAAeC,qBAAqBvB,MAA+B;IACxE,IAAI,CAACnC,gBAAgB;QACnB,OAAO,EAAE;IACX;IACA,OAAOA,eAAe0D,oBAAoB,CAACvB;AAC7C;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASwB,oBAAoBC,MAAc,EAAEtB,EAAU;IAC5D,OAAO;QACLuB,OAAO;QACPD;QACAtB;IACF;AACF"}

package/ios/AppIntentDonation.swift

@@ -0,0 +1,304 @@
+import AppIntents
+import ExpoModulesCore
+import Foundation
+
+/// An `AppIntent` that JavaScript can donate by name with `donateIntentAsync()`.
+///
+/// A donation tells the system that the user just did this in the app, so Siri, Spotlight and the
+/// Shortcuts app can suggest it later. The system needs a real intent value to learn from, and only
+/// the app target can build one, so each donatable intent builds itself from the params that
+/// JavaScript passed.
+///
+/// The params arrive as the intent's `DonationParams` record, so each field already has the type the
+/// intent declares, and a missing required field is rejected before the intent is built. An intent
+/// that takes no params from JavaScript can leave out both `DonationParams` and `init(donationParams:)`.
+public protocol DonatableAppIntent: AppIntent {
+  associatedtype DonationParams: Record = NoDonationParams
+
+  init(donationParams: DonationParams) async throws
+}
+
+/// The `DonationParams` of an intent that takes no params from JavaScript. Any params passed are
+/// ignored.
+public struct NoDonationParams: Record {
+  public init() {}
+}
+
+extension DonatableAppIntent where DonationParams == NoDonationParams {
+  /// An intent without params needs no donation code of its own: conforming is enough.
+  public init(donationParams: NoDonationParams) {
+    self.init()
+  }
+}
+
+internal enum AppIntentDonationFilter {
+  case ids([String])
+  case intent(String)
+  case entity(String, id: String)
+}
+
+/// The system predicate a filter resolves to. `IntentDonationMatchingPredicate` is opaque, so this is
+/// what the donor is handed instead, and what tests can inspect.
+internal enum AppIntentDonationMatch {
+  case donation(IntentDonationIdentifier)
+  case intentType(any AppIntent.Type)
+  case entity(EntityIdentifier)
+}
+
+/// The calls made to `IntentDonationManager`, behind a protocol so tests never donate to the device.
+internal protocol AppIntentDonor: Sendable {
+  func donate(_ intent: any AppIntent) async throws -> IntentDonationIdentifier
+  func deleteDonations(matching match: AppIntentDonationMatch) async throws -> [IntentDonationIdentifier]
+}
+
+internal struct SystemAppIntentDonor: AppIntentDonor {
+  func donate(_ intent: any AppIntent) async throws -> IntentDonationIdentifier {
+    return try await IntentDonationManager.shared.donate(intent: intent)
+  }
+
+  func deleteDonations(matching match: AppIntentDonationMatch) async throws -> [IntentDonationIdentifier] {
+    let manager = IntentDonationManager.shared
+    switch match {
+    case .donation(let identifier):
+      return try await manager.deleteDonations(matching: .donationIdentifier(identifier))
+    case .intentType(let intentType):
+      return try await manager.deleteDonations(matching: .intentType(intentType))
+    case .entity(let identifier):
+      return try await manager.deleteDonations(matching: .entityIdentifier(identifier))
+    }
+  }
+}
+
+/// Maps the names JavaScript donates by to the app-target intent types that can be donated.
+///
+/// Register each intent in the `OnCreate` of the `AppIntentsSetup` inline module. The name only has to
+/// match what JavaScript passes to `donateIntentAsync()` and `deleteDonationsAsync({ intent })`.
+/// Nothing links it to the name the intent passes to `AppIntentDispatcher.shared.dispatch(name:params:)`,
+/// but reusing that name, where there is one, gives JavaScript one name per intent.
+public final class AppIntentDonationRegistry: Sendable {
+  public static let shared = AppIntentDonationRegistry()
+
+  /// What `register(_:as:)` keeps for one name. The intent type is erased so that intents with
+  /// different `DonationParams` can share the registry, and `makeIntent` keeps the concrete type
+  /// that converting the params needs.
+  private struct Registration: Sendable {
+    let intentType: any AppIntent.Type
+    let makeIntent: @Sendable ([String: Any], AppContext) async throws -> any AppIntent
+  }
+
+  /// Registration happens on the main actor from `OnCreate`, while lookups come from the module's
+  /// async functions at the same time.
+  private let registrations = Mutex<[String: Registration]>([:])
+  private let donor: any AppIntentDonor
+  private let entities: AppEntityIdentifierRegistry
+
+  internal init(
+    donor: any AppIntentDonor = SystemAppIntentDonor(),
+    entities: AppEntityIdentifierRegistry = .shared
+  ) {
+    self.donor = donor
+    self.entities = entities
+  }
+
+  /// Registering a name again replaces its earlier intent. Deleting by `{ intent }` deletes by intent
+  /// type, so when two names are registered for one type, deleting by either name deletes the
+  /// donations made under both.
+  public func register<Intent: DonatableAppIntent>(_ name: String, as intentType: Intent.Type) {
+    let registration = Registration(intentType: intentType) { params, appContext in
+      let donationParams: Intent.DonationParams
+      do {
+        donationParams = try Intent.DonationParams.from(dictionary: params, appContext: appContext)
+      } catch {
+        throw InvalidDonationParamsException((intent: name, paramsType: "\(Intent.DonationParams.self)")).causedBy(
+          error
+        )
+      }
+      do {
+        return try await Intent(donationParams: donationParams)
+      } catch {
+        throw DonationIntentInitException((intent: name, error: error))
+      }
+    }
+    registrations.withLock {
+      $0[name] = registration
+    }
+  }
+
+  /// Builds the intent registered as `name` from `params`, donates it, and returns the donation id
+  /// JavaScript can later delete it by.
+  internal func donate(_ name: String, params: [String: Any], appContext: AppContext) async throws -> String {
+    let intent = try await registration(named: name).makeIntent(params, appContext)
+    return try encode(await donor.donate(intent))
+  }
+
+  /// Deletes the donations matching `filter`, and returns the ids of the ones that were deleted.
+  internal func deleteDonations(matching filter: AppIntentDonationFilter) async throws -> [String] {
+    switch filter {
+    case .ids(let ids):
+      // Every id is read before anything is deleted, so an unreadable id deletes nothing.
+      return try await deleteEach(ids.map { (id: $0, identifier: try decode($0)) })
+    case .intent(let name):
+      return try await donor.deleteDonations(matching: .intentType(registration(named: name).intentType)).map(encode)
+    case .entity(let entity, let id):
+      guard let identifier = entities.identifier(for: entity, id: id) else {
+        throw UnregisteredDonationEntityException((entity, id))
+      }
+      return try await donor.deleteDonations(matching: .entity(identifier)).map(encode)
+    }
+  }
+
+  /// `.donationIdentifiers(_:)` needs iOS 26.4 and its SDK, so each id is deleted on its own. A failed
+  /// id does not stop the ids after it, and the exception names which ids were deleted and which not.
+  private func deleteEach(_ donations: [(id: String, identifier: IntentDonationIdentifier)]) async throws -> [String] {
+    var deleted: [IntentDonationIdentifier] = []
+    var failed: [String] = []
+    var firstError: (any Error)?
+    for donation in donations {
+      do {
+        deleted += try await donor.deleteDonations(matching: .donation(donation.identifier))
+      } catch {
+        failed.append(donation.id)
+        firstError = firstError ?? error
+      }
+    }
+    let deletedIds = try deleted.map(encode)
+    if let firstError {
+      throw PartialDonationDeletionException((deleted: deletedIds, failed: failed)).causedBy(firstError)
+    }
+    return deletedIds
+  }
+
+  private func registration(named name: String) throws -> Registration {
+    guard let registration = registrations.withLock({ $0[name] }) else {
+      throw UnregisteredDonationIntentException(name)
+    }
+    return registration
+  }
+
+  private func encode(_ identifier: IntentDonationIdentifier) throws -> String {
+    // `JSONEncoder` only writes valid UTF-8, so there is nothing for a failable conversion to catch.
+    // swiftlint:disable:next optional_data_string_conversion
+    return String(decoding: try JSONEncoder().encode(identifier), as: UTF8.self)
+  }
+
+  private func decode(_ id: String) throws -> IntentDonationIdentifier {
+    do {
+      return try JSONDecoder().decode(IntentDonationIdentifier.self, from: Data(id.utf8))
+    } catch {
+      throw InvalidDonationIdentifierException(id)
+    }
+  }
+}
+
+/// The filter `deleteDonationsAsync()` receives. JavaScript types it as a union, so it arrives as one
+/// object whose keys say which variant it is.
+@Record
+internal struct AppIntentDonationFilterRecord {
+  var ids: [String]?
+  var intent: String?
+  var entity: String?
+  var id: String?
+
+  func toFilter() throws -> AppIntentDonationFilter {
+    switch (ids, intent, entity, id) {
+    case (let ids?, nil, nil, nil):
+      return .ids(ids)
+    case (nil, let intent?, nil, nil):
+      return .intent(intent)
+    case (nil, nil, let entity?, let id?):
+      return .entity(entity, id: id)
+    default:
+      throw InvalidDonationFilterException()
+    }
+  }
+}
+
+internal final class UnregisteredDonationIntentException: GenericException<String>, @unchecked Sendable {
+  override var reason: String {
+    return """
+      expo-app-intents has no intent registered for donation as '\(param)'. JavaScript can only name \
+      intents that app-target Swift has registered, because only the app target can build them. Make \
+      the intent conform to DonatableAppIntent, then add this to the OnCreate of your AppIntentsSetup \
+      module: AppIntentDonationRegistry.shared.register("\(param)", as: YourIntent.self)
+      """
+  }
+}
+
+internal final class InvalidDonationIdentifierException: GenericException<String>, @unchecked Sendable {
+  override var reason: String {
+    return """
+      expo-app-intents could not read the donation id '\(param)', so no donations were deleted. \
+      Donation ids are opaque, and one that was changed or built by hand no longer names a donation. \
+      Pass the id exactly as donateIntentAsync() or deleteDonationsAsync() returned it.
+      """
+  }
+}
+
+internal final class UnregisteredDonationEntityException: GenericException<(String, String)>, @unchecked Sendable {
+  override var reason: String {
+    let (entity, id) = param
+    return """
+      expo-app-intents could not delete donations for the '\(entity)' entity '\(id)'. This happens \
+      when no AppEntity is registered as '\(entity)'. It also happens when '\(id)' is not a valid \
+      identifier for that entity. Register the entity in the OnCreate of your AppIntentsSetup module with \
+      AppEntityIdentifierRegistry.shared.register("\(entity)", as: YourEntity.self), and pass an id \
+      that converts to the type of its id property.
+      """
+  }
+}
+
+/// The record's own exception, which names the field, is the cause.
+internal final class InvalidDonationParamsException: GenericException<(intent: String, paramsType: String)>,
+  @unchecked Sendable
+{
+  override var reason: String {
+    return """
+      expo-app-intents could not donate the '\(param.intent)' intent, because the params passed to \
+      donateIntentAsync() do not fit its DonationParams record \(param.paramsType). Nothing was \
+      donated. Pass every required field of that record, with the type the record declares.
+      """
+  }
+}
+
+/// Keeps the app's error in the reason rather than using `causedBy(_:)`: a cause that is not an
+/// `Exception` is described by its `localizedDescription`, which drops the text of a plain Swift error
+/// such as a `CustomStringConvertible` struct, and this error comes from app code.
+internal final class DonationIntentInitException: GenericException<(intent: String, error: any Error)>,
+  @unchecked Sendable
+{
+  override var reason: String {
+    return """
+      expo-app-intents could not donate the '\(param.intent)' intent, because its \
+      init(donationParams:) threw: \(param.error). Nothing was donated. Check that the params passed \
+      to donateIntentAsync() match what init(donationParams:) of the intent registered as \
+      '\(param.intent)' expects.
+      """
+  }
+}
+
+/// The first error the system reported is the cause.
+internal final class PartialDonationDeletionException: GenericException<(deleted: [String], failed: [String])>,
+  @unchecked Sendable
+{
+  override var reason: String {
+    return """
+      expo-app-intents could not delete every donation. Deleted: \(list(param.deleted)). Not \
+      deleted: \(list(param.failed)). Call deleteDonationsAsync() again with the ids that were not \
+      deleted.
+      """
+  }
+
+  private func list(_ ids: [String]) -> String {
+    return ids.isEmpty ? "none" : ids.map { "'\($0)'" }.joined(separator: ", ")
+  }
+}
+
+internal final class InvalidDonationFilterException: Exception, @unchecked Sendable {
+  override var reason: String {
+    return """
+      deleteDonationsAsync() needs exactly one of { ids }, { intent }, or { entity, id }, so it cannot \
+      tell which donations to delete. Pass one of those shapes, and call it once per filter to delete \
+      by more than one.
+      """
+  }
+}

package/ios/ExpoAppIntentsModule.swift

@@ -138,6 +138,19 @@ public final class ExpoAppIntentsModule: Module, @unchecked Sendable {
     AsyncFunction("refreshShortcutsAsync") { () async throws in
       try await self.refreshShortcuts()
     }
+
+    AsyncFunction("donateIntentAsync") { (name: String, params: [String: Any]?) async throws -> String in
+      guard let appContext = self.appContext else {
+        throw Exceptions.AppContextLost()
+      }
+      // The registry converts `params` to the `DonationParams` record of the intent registered as
+      // `name`, since only that registration knows the record type.
+      return try await AppIntentDonationRegistry.shared.donate(name, params: params ?? [:], appContext: appContext)
+    }
+
+    AsyncFunction("deleteDonationsAsync") { (filter: AppIntentDonationFilterRecord) async throws -> [String] in
+      return try await AppIntentDonationRegistry.shared.deleteDonations(matching: filter.toFilter())
+    }
   }
 
   /// Installs the `appEntityIdentifier` factory. Both factories take the `AppContext` from the call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-app-intents",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Expose Apple App Intents (Siri, Shortcuts, Spotlight, Apple Intelligence) from Expo apps",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -28,16 +28,16 @@
   "license": "MIT",
   "homepage": "https://docs.expo.dev/versions/latest/sdk/app-intents",
   "devDependencies": {
-    "@testing-library/react-native": "^13.3.0",
+    "@testing-library/react-native": "^14.0.1",
     "@types/jest": "^29.2.1",
     "@types/node": "^22.14.0",
     "@types/prompts": "^2.4.9",
     "@types/react": "~19.3.0",
-    "expo": "58.0.0",
-    "expo-module-scripts": "56.0.4"
+    "expo": "58.0.2",
+    "expo-module-scripts": "56.0.5"
   },
   "dependencies": {
-    "@expo/ui": "^58.0.9",
+    "@expo/ui": "^58.0.11",
     "commander": "^12.1.0",
     "prompts": "^2.4.2"
   },

package/src/ExpoAppIntents.types.ts

@@ -87,6 +87,33 @@ export type AppEntityIdentifierModifier = ModifierConfig & {
   id: string;
 };
 
+/**
+ * A value that can be passed as an App Intent parameter: anything JSON can represent.
+ */
+export type AppIntentJSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | AppIntentJSONValue[]
+  | { [key: string]: AppIntentJSONValue };
+
+/**
+ * Selects the donations that `deleteDonationsAsync()` deletes. Pass one of these shapes:
+ *
+ * - `{ ids }` deletes the donations with the given IDs, as returned by `donateIntentAsync()`.
+ * - `{ intent }` deletes every donation of the intent type registered under that name. When
+ *   several names are registered for one intent type, this also deletes the donations made under
+ *   the other names.
+ * - `{ entity, id }` deletes every donation that refers to the given entity. The `entity` value
+ *   must be registered with `AppEntityIdentifierRegistry.shared.register(_:as:)` or
+ *   `AppEntityIdentifierRegistry.shared.registerIndexed(_:as:)`.
+ */
+export type AppIntentDonationFilter =
+  | { ids: string[] }
+  | { intent: string }
+  | { entity: string; id: string };
+
 export type ExpoAppIntentsModuleEvents = {
   onIntent: (invocation: AppIntentInvocation) => void;
 };

package/src/ExpoAppIntentsModule.ts

@@ -1,8 +1,10 @@
 import { NativeModule, requireOptionalNativeModule } from 'expo-modules-core';
 
 import type {
+  AppIntentDonationFilter,
   AppIntentEntity,
   AppIntentInvocation,
+  AppIntentJSONValue,
   ExpoAppIntentsModuleEvents,
 } from './ExpoAppIntents.types';
 
@@ -14,6 +16,8 @@ declare class ExpoAppIntentsNativeModule extends NativeModule<ExpoAppIntentsModu
   reindexEntitiesAsync(kind: string | null): Promise<void>;
   getEntityCatalogAsync(kind: string): Promise<AppIntentEntity[]>;
   refreshShortcutsAsync(): Promise<void>;
+  donateIntentAsync(name: string, params?: Record<string, AppIntentJSONValue>): Promise<string>;
+  deleteDonationsAsync(filter: AppIntentDonationFilter): Promise<string[]>;
 }
 
 export default requireOptionalNativeModule<ExpoAppIntentsNativeModule>('ExpoAppIntents');

package/src/index.ts

@@ -3,8 +3,10 @@ import { useEffect, useRef } from 'react';
 
 import type {
   AppEntityIdentifierModifier,
+  AppIntentDonationFilter,
   AppIntentEntity,
   AppIntentInvocation,
+  AppIntentJSONValue,
   AppIntentsHandler,
 } from './ExpoAppIntents.types';
 import ExpoAppIntents from './ExpoAppIntentsModule';
@@ -266,6 +268,61 @@ export async function refreshShortcutsAsync(): Promise<void> {
   return ExpoAppIntents.refreshShortcutsAsync();
 }
 
+/**
+ * Tells the system that the user just performed an App Intent's action in your app, for example
+ * ordering food from a screen rather than through Siri. The system learns from donations and can
+ * suggest the action later on the Lock Screen, in Siri Suggestions, and in Spotlight.
+ *
+ * The `name` must be registered from app-target Swift with
+ * `AppIntentDonationRegistry.shared.register(_:as:)`, on an intent that conforms to
+ * `DonatableAppIntent`. Native code converts `params` to the `DonationParams` record of that intent,
+ * and the intent builds itself from the record in its `init(donationParams:)`.
+ *
+ * The returned promise is fulfilled with an ID for the donation, which
+ * [`deleteDonationsAsync()`](#appintentsdeletedonationsasyncfilter) accepts, or with `null` when
+ * App Intents are unavailable. It is rejected when no intent is registered as `name`, when `params`
+ * misses a required field of the record or has a field of the wrong type, when the intent cannot be
+ * built from the record, or when the system fails to record the donation.
+ *
+ * > **Note:** The ID is the system's donation identifier in its encoded form. Store it only for as
+ * > long as you need it. An iOS update may change how the system encodes identifiers, and an ID
+ * > stored before such an update may then be rejected. To delete donations without stored IDs,
+ * > delete by `intent` or by `entity`.
+ *
+ * @platform ios
+ */
+export async function donateIntentAsync(
+  name: string,
+  params?: Record<string, AppIntentJSONValue>
+): Promise<string | null> {
+  if (!ExpoAppIntents) {
+    return null;
+  }
+  return ExpoAppIntents.donateIntentAsync(name, params);
+}
+
+/**
+ * Deletes donations made with [`donateIntentAsync()`](#appintentsdonateintentasyncname-params), so
+ * the system stops suggesting them. Delete donations when what they refer to is gone, for example
+ * after the user deletes an order, or when the user signs out.
+ *
+ * The returned promise is fulfilled with the IDs of the deleted donations, or with an empty array
+ * when App Intents are unavailable. It is rejected when `filter` names an intent or entity that is
+ * not registered, contains an ID that cannot be read, or contains an entity `id` that cannot be
+ * converted to the ID type of that entity. In those cases nothing is deleted. With `ids`, every ID
+ * is attempted. When the system fails to delete one or more of them, the promise is rejected with
+ * an error that lists the deleted IDs and the IDs that were not deleted. With `intent` or
+ * `entity`, the promise is rejected with the system error when the system fails to delete.
+ *
+ * @platform ios
+ */
+export async function deleteDonationsAsync(filter: AppIntentDonationFilter): Promise<string[]> {
+  if (!ExpoAppIntents) {
+    return [];
+  }
+  return ExpoAppIntents.deleteDonationsAsync(filter);
+}
+
 /**
  * Returns an ExpoUI SwiftUI modifier config that ties a view to an AppEntity identifier.
  *