capacitor-apple-intelligence 1.0.0

package/CapacitorAppleIntelligence.podspec

@@ -0,0 +1,13 @@
+Pod::Spec.new do |s|
+  s.name = 'CapacitorAppleIntelligence'
+  s.version = '1.0.0'
+  s.summary = 'Capacitor plugin for Apple Intelligence with schema-constrained JSON generation'
+  s.license = 'MIT'
+  s.homepage = 'https://github.com/farabiabdelwahe/capacitor-apple-intelligence'
+  s.author = 'Farabi Abdelwahed'
+  s.source = { :git => 'https://github.com/farabiabdelwahe/capacitor-apple-intelligence.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/AppleIntelligencePlugin/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Farabi Abdelwahed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorAppleIntelligence",
+    platforms: [.iOS(.v14)],
+    products: [
+        .library(
+            name: "CapacitorAppleIntelligence",
+            targets: ["AppleIntelligencePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", branch: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "AppleIntelligencePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/AppleIntelligencePlugin"),
+        .testTarget(
+            name: "AppleIntelligencePluginTests",
+            dependencies: ["AppleIntelligencePlugin"],
+            path: "ios/Tests/AppleIntelligencePluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,346 @@
+# capacitor-apple-intelligence
+
+A production-ready Capacitor v8 plugin that exposes **Apple Intelligence** with **schema-constrained JSON generation** for structured AI responses.
+
+## Features
+
+- 🧠 **On-device AI** - Uses Apple's Foundation Models framework for local, private inference
+- 📋 **Schema-constrained output** - Guarantees JSON output matching your provided schema
+- 🔄 **Automatic retry** - Retries generation once if validation fails
+- ✅ **Runtime validation** - Validates output against JSON schema before returning
+- 🔒 **Privacy-first** - No network calls, all processing happens on-device
+- 📱 **iOS only** - Designed specifically for Apple Intelligence on iOS 26+
+
+## Requirements
+
+- **iOS 26+** (Apple Intelligence requires iOS 26 or later)
+- **Capacitor 8.0+**
+- **Xcode 26+**
+- **Apple Silicon device** (iPhone 15 Pro or later, or M-series iPads)
+
+> ⚠️ **Note**: Apple Intelligence must be enabled on the device for this plugin to work.
+
+## Installation
+
+```bash
+npm install capacitor-apple-intelligence
+npx cap sync
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { AppleIntelligence } from 'capacitor-apple-intelligence';
+
+const result = await AppleIntelligence.generate({
+  messages: [
+    { role: "user", content: "List 3 popular programming languages" }
+  ],
+  response_format: {
+    type: "json_schema",
+    schema: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          paradigm: { type: "string" },
+          yearCreated: { type: "number" }
+        },
+        required: ["name", "paradigm", "yearCreated"]
+      }
+    }
+  }
+});
+
+if (result.success) {
+  console.log(result.data);
+  // [
+  //   { name: "Python", paradigm: "Multi-paradigm", yearCreated: 1991 },
+  //   { name: "JavaScript", paradigm: "Event-driven", yearCreated: 1995 },
+  //   { name: "Rust", paradigm: "Systems", yearCreated: 2010 }
+  // ]
+} else {
+  console.error(result.error?.code, result.error?.message);
+}
+```
+
+### With System Prompt
+
+```typescript
+const result = await AppleIntelligence.generate({
+  messages: [
+    { 
+      role: "system", 
+      content: "You are a helpful assistant that organizes tasks." 
+    },
+    { 
+      role: "user", 
+      content: "Create a list of tasks for planning a project" 
+    }
+  ],
+  response_format: {
+    type: "json_schema",
+    schema: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "string" },
+          estimatedHours: { type: "number" }
+        },
+        required: ["title", "priority"]
+      }
+    }
+  }
+});
+```
+
+### Nested Object Schema
+
+```typescript
+const result = await AppleIntelligence.generate({
+  messages: [
+    { role: "user", content: "Create a sample user profile" }
+  ],
+  response_format: {
+    type: "json_schema",
+    schema: {
+      type: "object",
+      properties: {
+        user: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            email: { type: "string" },
+            age: { type: "number" }
+          },
+          required: ["name", "email"]
+        },
+        preferences: {
+          type: "object",
+          properties: {
+            theme: { type: "string" },
+            notifications: { type: "boolean" }
+          }
+        }
+      },
+      required: ["user"]
+    }
+  }
+});
+```
+
+### Plain Text Generation
+
+Generate plain text responses without JSON schema constraints:
+
+```typescript
+const result = await AppleIntelligence.generateText({
+  messages: [
+    { role: "system", content: "You are a creative writing assistant." },
+    { role: "user", content: "Write a short poem about the ocean" }
+  ]
+});
+
+if (result.success) {
+  console.log(result.content);
+  // "Waves crash upon the shore,
+  //  Endless depths forevermore..."
+}
+```
+
+### Text Generation with Language
+
+Generate text in a specific language using either language codes or full names:
+
+```typescript
+const result = await AppleIntelligence.generateTextWithLanguage({
+  messages: [
+    { role: "user", content: "Describe a beautiful sunset" }
+  ],
+  language: "es"  // or "Spanish"
+});
+
+if (result.success) {
+  console.log(result.content);
+  // "El atardecer pinta el cielo con tonos dorados y rosados..."
+}
+```
+
+Supported language codes: `en`, `es`, `fr`, `de`, `ja`, `zh`, `it`, `pt`, `ru`, `ar`, `ko`
+
+## API
+
+### `checkAvailability()`
+
+Check if Apple Intelligence is available on the current device. **Call this first** before using other methods.
+
+#### Response
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `available` | `boolean` | Whether Apple Intelligence is available |
+| `error` | `GenerateError` | Error details (if unavailable) |
+
+#### Example
+
+```typescript
+const result = await AppleIntelligence.checkAvailability();
+
+if (result.available) {
+  console.log('Apple Intelligence is ready!');
+} else {
+  console.log('Not available:', result.error?.message);
+  // "Apple Intelligence requires iOS 26 or later..."
+}
+```
+
+---
+
+### `generate(request)`
+
+Generate structured JSON output using Apple Intelligence.
+
+#### Request
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `messages` | `Message[]` | Array of conversation messages |
+| `response_format` | `ResponseFormat` | Schema specification for the output |
+
+#### Message
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `role` | `"system" \| "user"` | The role of the message sender |
+| `content` | `string` | The text content of the message |
+
+#### ResponseFormat
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `"json_schema"` | Must be `"json_schema"` |
+| `schema` | `object` | JSON Schema specification |
+
+#### Response
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `success` | `boolean` | Whether generation succeeded |
+| `data` | `any` | The parsed JSON data (on success) |
+| `error` | `GenerateError` | Error details (on failure) |
+
+#### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `UNAVAILABLE` | iOS < 26 or Apple Intelligence not available |
+| `INVALID_JSON` | Model output was not valid JSON |
+| `SCHEMA_MISMATCH` | JSON valid but doesn't match schema |
+| `NATIVE_ERROR` | Other Swift/Foundation Models errors |
+
+### `generateText(request)`
+
+Generate plain text output using Apple Intelligence.
+
+#### Request
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `messages` | `Message[]` | Array of conversation messages |
+
+#### Response
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `success` | `boolean` | Whether generation succeeded |
+| `content` | `string` | The generated text (on success) |
+| `error` | `GenerateError` | Error details (on failure) |
+
+### `generateTextWithLanguage(request)`
+
+Generate plain text output in a specific language using Apple Intelligence.
+
+#### Request
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `messages` | `Message[]` | Array of conversation messages |
+| `language` | `string` | Target language - supports codes ("en", "es", "de") or full names ("English", "Spanish", "German") |
+
+#### Response
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `success` | `boolean` | Whether generation succeeded |
+| `content` | `string` | The generated text (on success) |
+| `error` | `GenerateError` | Error details (on failure) |
+
+## How It Works
+
+1. **Schema Injection**: The plugin injects your JSON schema into the system prompt with strict instructions
+2. **Generation**: Uses Apple's Foundation Models framework to generate a response
+3. **Parsing**: Parses the raw text output as JSON
+4. **Validation**: Validates the JSON against your provided schema
+5. **Retry**: If validation fails, retries once with a corrective prompt
+6. **Return**: Returns structured success/error response
+
+## Supported Schema Types
+
+- `object` - With `properties` and `required` fields
+- `array` - With `items` schema and optional `minItems`/`maxItems`
+- `string`
+- `number` / `integer`
+- `boolean`
+- `null`
+
+## Error Handling
+
+The plugin always returns a structured response, never throws:
+
+```typescript
+const result = await AppleIntelligence.generate({...});
+
+if (!result.success) {
+  switch (result.error?.code) {
+    case 'UNAVAILABLE':
+      // Show fallback UI or use alternative
+      break;
+    case 'INVALID_JSON':
+    case 'SCHEMA_MISMATCH':
+      // Retry with different prompt or handle gracefully
+      break;
+    case 'NATIVE_ERROR':
+      // Log error for debugging
+      console.error(result.error.message);
+      break;
+  }
+}
+```
+
+## Web Support
+
+This plugin is iOS-only. On web platforms, it returns:
+
+```typescript
+{
+  success: false,
+  error: {
+    code: 'UNAVAILABLE',
+    message: 'Apple Intelligence is only available on iOS 26+ devices...'
+  }
+}
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.

package/dist/esm/definitions.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Apple Intelligence Plugin for Capacitor v8
+ *
+ * Provides schema-constrained JSON generation using Apple's on-device
+ * Foundation Models framework, behaving like Groq/Gemini response_format: json_object.
+ *
+ * @module capacitor-apple-intelligence
+ */
+/**
+ * Message role for conversation history.
+ */
+export type MessageRole = 'system' | 'user';
+/**
+ * A message in the conversation.
+ */
+export interface Message {
+    /**
+     * The role of the message sender.
+     * - 'system': Instructions for the AI model
+     * - 'user': User input/queries
+     */
+    role: MessageRole;
+    /**
+     * The text content of the message.
+     */
+    content: string;
+}
+/**
+ * JSON Schema response format specification.
+ */
+export interface ResponseFormat {
+    /**
+     * The type of response format. Must be 'json_schema'.
+     */
+    type: 'json_schema';
+    /**
+     * The JSON schema that the model output must conform to.
+     * Supports standard JSON Schema properties including:
+     * - type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null'
+     * - properties: Object defining property schemas
+     * - required: Array of required property names
+     * - items: Schema for array items
+     */
+    schema: Record<string, unknown>;
+}
+/**
+ * Request payload for the generate method.
+ */
+export interface GenerateRequest {
+    /**
+     * Array of messages forming the conversation context.
+     * Should include system messages for instructions and
+     * user messages for the actual query.
+     */
+    messages: Message[];
+    /**
+     * Response format specification requiring JSON schema compliance.
+     */
+    response_format: ResponseFormat;
+}
+/**
+ * Error codes returned by the plugin.
+ */
+export type ErrorCode = 'INVALID_JSON' | 'SCHEMA_MISMATCH' | 'UNAVAILABLE' | 'NATIVE_ERROR';
+/**
+ * Structured error object returned on failure.
+ */
+export interface GenerateError {
+    /**
+     * Error code for programmatic handling.
+     * - INVALID_JSON: Model output was not valid JSON
+     * - SCHEMA_MISMATCH: JSON valid but doesn't match provided schema
+     * - UNAVAILABLE: iOS version < 26 or Apple Intelligence not available
+     * - NATIVE_ERROR: Other Swift/Foundation Models errors
+     */
+    code: ErrorCode;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+}
+/**
+ * Response from the generate method.
+ */
+export interface GenerateResponse {
+    /**
+     * Whether the generation was successful.
+     */
+    success: boolean;
+    /**
+     * The parsed JSON data on success.
+     * The structure will match the provided schema.
+     */
+    data?: unknown;
+    /**
+     * Error details on failure.
+     * Only present when success is false.
+     */
+    error?: GenerateError;
+}
+/**
+ * Apple Intelligence Plugin interface.
+ *
+ * Provides access to Apple's on-device Foundation Models for
+ * schema-constrained JSON generation.
+ */
+export interface AppleIntelligencePlugin {
+    /**
+     * Generate structured JSON output using Apple Intelligence.
+     *
+     * This method:
+     * 1. Injects the JSON schema into the system prompt
+     * 2. Instructs the model to return ONLY valid JSON
+     * 3. Validates the output against the provided schema
+     * 4. Retries once on validation failure
+     *
+     * @param request - The generation request containing messages and schema
+     * @returns Promise resolving to a structured response with success/error
+     *
+     * @example
+     * ```typescript
+     * const result = await AppleIntelligence.generate({
+     *   messages: [
+     *     { role: "system", content: "You are a helpful assistant." },
+     *     { role: "user", content: "List 3 fruits" }
+     *   ],
+     *   response_format: {
+     *     type: "json_schema",
+     *     schema: {
+     *       type: "array",
+     *       items: {
+     *         type: "object",
+     *         properties: {
+     *           name: { type: "string" },
+     *           color: { type: "string" }
+     *         },
+     *         required: ["name", "color"]
+     *       }
+     *     }
+     *   }
+     * });
+     *
+     * if (result.success) {
+     *   console.log(result.data);
+     *   // [{ name: "Apple", color: "red" }, ...]
+     * }
+     * ```
+     */
+    generate(request: GenerateRequest): Promise<GenerateResponse>;
+    /**
+     * Generate plain text output using Apple Intelligence.
+     *
+     * @param request - The generation request containing messages
+     * @returns Promise resolving to a text response with success/error
+     */
+    generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
+    /**
+     * Generate plain text output using Apple Intelligence with a specific target language.
+     *
+     * @param request - The generation request containing messages and target language
+     * @returns Promise resolving to a text response with success/error
+     */
+    generateTextWithLanguage(request: GenerateTextWithLanguageRequest): Promise<GenerateTextResponse>;
+    /**
+     * Check if Apple Intelligence is available on this device.
+     *
+     * @returns Promise resolving to availability status
+     */
+    checkAvailability(): Promise<AvailabilityResponse>;
+}
+/**
+ * Request payload for text generation.
+ */
+export interface GenerateTextRequest {
+    /**
+     * Array of messages forming the conversation context.
+     */
+    messages: Message[];
+}
+/**
+ * Request payload for text generation with language.
+ */
+export interface GenerateTextWithLanguageRequest {
+    /**
+     * Array of messages forming the conversation context.
+     */
+    messages: Message[];
+    /**
+     * Target language for the response (e.g., "English", "Spanish", "French").
+     */
+    language: string;
+}
+/**
+ * Response for text generation.
+ */
+export interface GenerateTextResponse {
+    /**
+     * Whether the generation was successful.
+     */
+    success: boolean;
+    /**
+     * The generated text content on success.
+     */
+    content?: string;
+    /**
+     * Error details on failure.
+     * Only present when success is false.
+     */
+    error?: GenerateError;
+}
+/**
+ * Response for availability check.
+ */
+export interface AvailabilityResponse {
+    /**
+     * Whether Apple Intelligence is available on this device.
+     */
+    available: boolean;
+    /**
+     * Error details if unavailable.
+     */
+    error?: GenerateError;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,10 @@
+/**
+ * Apple Intelligence Plugin for Capacitor v8
+ *
+ * Provides schema-constrained JSON generation using Apple's on-device
+ * Foundation Models framework, behaving like Groq/Gemini response_format: json_object.
+ *
+ * @module capacitor-apple-intelligence
+ */
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/esm/index.d.ts

@@ -0,0 +1,33 @@
+import type { AppleIntelligencePlugin } from './definitions';
+/**
+ * Apple Intelligence Plugin instance.
+ *
+ * Provides schema-constrained JSON generation using Apple's on-device
+ * Foundation Models framework.
+ *
+ * @example
+ * ```typescript
+ * import { AppleIntelligence } from 'capacitor-apple-intelligence';
+ *
+ * const result = await AppleIntelligence.generate({
+ *   messages: [{ role: "user", content: "Suggest 3 books" }],
+ *   response_format: {
+ *     type: "json_schema",
+ *     schema: {
+ *       type: "array",
+ *       items: {
+ *         type: "object",
+ *         properties: {
+ *           title: { type: "string" },
+ *           author: { type: "string" }
+ *         },
+ *         required: ["title", "author"]
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const AppleIntelligence: AppleIntelligencePlugin;
+export * from './definitions';
+export { AppleIntelligence };