@cometchat/skills 4.3.0 → 4.4.1

package/skills/cometchat-i18n/SKILL.md

@@ -3,18 +3,19 @@ name: cometchat-i18n
 description: Localization (i18n) across all CometChat UI Kit families — React, React Native, Angular, Android (V5/V6), iOS, Flutter (V5/V6). Covers CometChatLocalize.init signature differences (positional vs object), bundled languages, custom-language registration, RTL support, fallback to English, and cross-family drift risks. Cross-family — applies wherever the agent is configuring CometChat localization.
 license: "MIT"
 compatibility: "All CometChat UI Kit families v4.x / v5.x / v6.x"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
   tags: "cometchat i18n localization l10n cometchatlocalize languages rtl arabic hebrew bundled-languages custom-language fallback cross-family"
 ---
 
+> **Ground truth:** the UI Kit `CometChatLocalize` API + `docs/fundamentals`. **Official docs:** https://www.cometchat.com/docs/fundamentals/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 Localize the CometChat UI Kit to the user's language. Every kit ships with English + ~15 bundled languages (Arabic, Bengali, Chinese, German, Spanish, French, Hindi, Indonesian, Italian, Japanese, Korean, Malay, Portuguese, Russian, Swedish, Turkish — exact set varies by kit version). Custom languages can be added at runtime.
 
-The biggest gotcha: **the `init` signature differs across kits and major versions**. The same audit pass that caught calls API drift caught one of these too (Angular Localize positional signature) — this skill is the canonical reference.
+The biggest gotcha: **the localization API differs across kits.** Web + Angular v5 use `CometChatLocalize.init({ ... })` (object); **React Native v5 uses a `<CometChatI18nProvider>` component + `useCometChatTranslation` hook (no `CometChatLocalize.init`)**; **Android uses `CometChatLocalize.setLocale(context, "es")`** (Context + code String); **iOS uses `CometChatLocalize.set(locale: "es")`**; **Flutter has no `CometChatLocalize` class at all — register the kit's `Translations` localization delegate.** (Angular's positional `init("es")` was a v4-only form — v5 moved to the object signature, matching React.) This skill is the canonical reference.
 
 ---
 
@@ -33,78 +34,108 @@ CometChatLocalize.init({
 
 Object literal. `init({ ... })`.
 
-### React Native (v5) — object signature
+### React Native (v5) — `CometChatI18nProvider` (NOT `CometChatLocalize.init`)
 
-```ts
-import { CometChatLocalize } from "@cometchat/chat-uikit-react-native";
+The RN v5 kit does **not** export a `CometChatLocalize` class with `.init(...)` (that was the v4 RN API). v5 localizes through a **provider component** + a hook. Wrap your app (inside `CometChatThemeProvider`) and read strings with `useCometChatTranslation`:
 
-CometChatLocalize.init({
-  language: "es",
-  fallbackLanguage: "en",
-});
+```tsx
+import {
+  CometChatThemeProvider,
+  CometChatI18nProvider,
+} from "@cometchat/chat-uikit-react-native";
+
+const App = () => (
+  <CometChatThemeProvider theme={{ mode: "light" }}>
+    {/* autoDetectLanguage reads the device locale; or pin one with selectedLanguage="es" */}
+    <CometChatI18nProvider autoDetectLanguage={true} fallbackLanguage="en">
+      {/* your screens / kit components */}
+    </CometChatI18nProvider>
+  </CometChatThemeProvider>
+);
+
+// In a component:
+import { useCometChatTranslation } from "@cometchat/chat-uikit-react-native";
+const { t } = useCometChatTranslation();
+// t("CHATS")
 ```
 
-Same object signature as React.
+`CometChatI18nProviderProps`: `selectedLanguage?`, `autoDetectLanguage?: boolean`, `fallbackLanguage?`, `translations?: { [code]: {...} }` (verified vs `shared/resources/CometChatLocalizeNew/CometChatI18nProvider.tsx`). For imperative switching there's `setGlobalLanguage(language, translations?, fallback?)`.
 
-### Angular (v4) — POSITIONAL signature
+### Angular (v5) — OBJECT signature
 
 ```ts
 import { CometChatLocalize } from "@cometchat/chat-uikit-angular";
 
-CometChatLocalize.init("es");
-// or with custom resources:
-CometChatLocalize.init("es", { es: { CHAT: "Charla" } });
+CometChatLocalize.init({ language: "es" });
+// with more options:
+CometChatLocalize.init({
+  language: "es",
+  fallbackLanguage: "en-US",
+  timezone: "Europe/Madrid",
+});
 ```
 
-**Positional, not object.** This was the v4.0 audit fix — calling `.init({ language: "es" })` on Angular sets `language = [object Object]` and silently breaks translations. The skill's verification checklist flags this drift.
+**Object literal, not positional** — in v5 (`@cometchat/chat-uikit-angular@5`), `init(settings: LocalizationSettings)` takes an object, the same shape as React. (Verified in `projects/cometchat-uikit/src/lib/resources/CometChatLocalize/cometchat-localize.ts` — `static init(settings: LocalizationSettings)`.) The old positional `init("es")` form was the **v4** Angular API and no longer applies. Switch language at runtime with `CometChatLocalize.setCurrentLanguage("fr")`, read keys with `getLocalizedString(key)`, and add custom strings with `addTranslation({ ... })`.
 
 ### Android V5 — Java/Kotlin static method
 
 ```kotlin
-// Kotlin
-CometChatLocalize.setLocale(Locale.forLanguageTag("es"))
+// Kotlin — takes (Context, language-code String). Language.* are String constants.
+CometChatLocalize.setLocale(context, Language.SPANISH)   // or "es"
 ```
 
 ```java
 // Java
-CometChatLocalize.setLocale(Locale.forLanguageTag("es"));
+CometChatLocalize.setLocale(context, Language.SPANISH);  // or "es"
 ```
 
-`setLocale`, not `init`. Takes a `java.util.Locale`.
+`setLocale`, not `init`. **Signature is `setLocale(Context, @Language.Code String)`** — a Context plus a two-letter language-code String (NOT a `java.util.Locale`). `Language` exposes `ENGLISH="en"`, `SPANISH="es"`, `FRENCH="fr"`, `GERMAN="de"`, … (verified vs `chatuikit/.../localise/CometChatLocalize.java` + `Language.kt`).
 
-### Android V6 (beta) — same as V5
+### Android V6 (stable) — same as V5
 
-V6 keeps the `setLocale(Locale)` API. No drift here.
+V6 keeps the same API: `CometChatLocalize.setLocale(context, "es")` (verified vs `chatuikit-kotlin/.../localise/CometChatLocalize.kt:22` — `fun setLocale(context: Context, language: String)`). No drift between V5 and V6.
 
 ### iOS V5
 
 ```swift
 import CometChatUIKitSwift
 
-CometChatLocalize.setLocale(locale: "es")
+CometChatLocalize.set(locale: "es")   // or set(locale: Language.spanish)
 ```
 
-`setLocale(locale:)`. Takes a String, not `Locale`.
-
-### Flutter V5 (GetX-based)
-
-```dart
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
-
-CometChatLocalize.init(language: 'es');
-```
+The method is **`set(locale:)`**, not `setLocale(...)`. It takes a String (or a `Language`) — `public class func set(locale: String)` / `set(locale: Language)` (verified vs `Components/Shared/Helpers/CometChatLocalize/CometChatLocalize.swift:78,82`). There is no `setStringResources` — override individual strings via your app's `Localizable.strings`.
 
-Named-arg, not positional. Single string.
+### Flutter V5 + V6 — there is NO `CometChatLocalize.init(...)`
 
-### Flutter V6 (Bloc-based)
+> **Verified against the kit source + docs (`ui-kits/cometchat-uikit-flutter-v6`, `documentation/docs/ui-kit/flutter/localize.mdx`): Flutter does NOT expose a `CometChatLocalize` class.** Localization is wired the idiomatic Flutter way — register the kit's `Translations` localization delegate on your `MaterialApp` and drive the language through the app's `Locale`. Earlier drafts of this skill showed `CometChatLocalize.init(language: 'es')`; that symbol does not exist in the Flutter UI Kit (V5 or V6) — do not emit it.
 
 ```dart
-import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-
-CometChatLocalize.init(language: 'es');
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc; // V6
+// V5: import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart' as cc; (5.2.x)
+
+MaterialApp(
+  // Language follows the app Locale. Set `locale:` to force one, or omit to
+  // follow the device + supportedLocales.
+  locale: const Locale('es'),
+  supportedLocales: const [
+    Locale('en'), Locale('ar'), Locale('de'), Locale('es'), Locale('fr'),
+    Locale('hi'), Locale('ja'), Locale('ko'), Locale('pt'), Locale('ru'),
+    Locale('zh'), // …19 supported total — see the docs list
+  ],
+  localizationsDelegates: const [
+    cc.Translations.delegate,            // ← the CometChat UI Kit strings
+    GlobalMaterialLocalizations.delegate,
+    GlobalWidgetsLocalizations.delegate,
+    GlobalCupertinoLocalizations.delegate,
+  ],
+  home: const YourHomeScreen(),
+);
 ```
 
-Same as V5 in Flutter — named arg.
+Read a translated string with `cc.Translations.of(context).users`. Add a custom
+language or override one by subclassing `cc.Translations` and registering your
+own `LocalizationsDelegate` *before* `cc.Translations.delegate` in the list
+(full recipe in `documentation/docs/ui-kit/flutter/localize.mdx`).
 
 ---
 
@@ -113,13 +144,13 @@ Same as V5 in Flutter — named arg.
 | Family | Init call | Notes |
 |---|---|---|
 | React (v6) | `CometChatLocalize.init({ language, fallbackLanguage })` | Object |
-| React Native (v5) | `CometChatLocalize.init({ language, fallbackLanguage })` | Object |
-| **Angular (v4)** | `CometChatLocalize.init("es")` | **Positional — drift trap** |
-| Android (V5/V6) | `CometChatLocalize.setLocale(Locale.forLanguageTag("es"))` | Method name `setLocale`, takes `Locale` |
-| iOS (V5) | `CometChatLocalize.setLocale(locale: "es")` | Method name `setLocale`, takes String |
-| Flutter (V5/V6) | `CometChatLocalize.init(language: 'es')` | Named arg |
+| React Native (v5) | `<CometChatI18nProvider autoDetectLanguage selectedLanguage="es" fallbackLanguage="en">` + `useCometChatTranslation()` | **Provider component, NOT `CometChatLocalize.init`** |
+| Angular (v5) | `CometChatLocalize.init({ language, fallbackLanguage })` | Object (same shape as React) |
+| Android (V5/V6) | `CometChatLocalize.setLocale(context, "es")` | Method `setLocale(Context, String code)` — NOT a `Locale` |
+| iOS (V5) | `CometChatLocalize.set(locale: "es")` | Method `set(locale:)` (String or `Language`) — NOT `setLocale` |
+| Flutter (V5/V6) | `MaterialApp(localizationsDelegates: [cc.Translations.delegate, …], supportedLocales: […], locale: Locale('es'))` | **No `CometChatLocalize`** — register the kit's `Translations` delegate + drive via `Locale`; read with `Translations.of(context)` |
 
-The agent must consult this table before writing any localization code. **Verify against the installed package's type definitions** if uncertain — symbol drift between minor versions is real (the React v5 → v6 changed from positional to object).
+The agent must consult this table before writing any localization code. **Verify against the installed package's type definitions** if uncertain — the localization surface genuinely differs per family (e.g. React Native moved from a `CometChatLocalize` class to the `<CometChatI18nProvider>` component; Flutter never had a `CometChatLocalize` class).
 
 ---
 
@@ -130,7 +161,7 @@ After CometChat init is configured but before mounting any kit components:
 ```ts
 // React example — in your provider
 useEffect(() => {
-  CometChatUIKit.init(settings).then(() => {
+  CometChatUIKit.init(settings)?.then(() => {
     CometChatLocalize.init({ language: getUserLocale(), fallbackLanguage: "en" });
     // Now mount kit components
   });
@@ -138,21 +169,25 @@ useEffect(() => {
 ```
 
 ```kotlin
-// Android — in Application.onCreate
+// Android — in Application.onCreate. setLocale takes (Context, code String).
 override fun onCreate() {
   super.onCreate()
-  val settings = UIKitSettings.Builder()/* ... */.build()
-  CometChatUIKit.init(this, settings) {
-    CometChatLocalize.setLocale(Locale.forLanguageTag(getUserLocale()))
-  }
+  val settings = UIKitSettings.UIKitSettingsBuilder()/* ... */.build()
+  CometChatUIKit.init(this, settings, object : CometChat.CallbackListener<String>() {
+    override fun onSuccess(p: String) {
+      CometChatLocalize.setLocale(this@MyApp, getUserLocale())   // e.g. "es"
+    }
+    override fun onError(e: CometChatException) {}
+  })
 }
 ```
 
 ```swift
-// iOS — in App.init or AppDelegate
+// iOS — in App.init or AppDelegate. The method is set(locale:), takes a String.
 CometChat.init(appId: ...) { _, error in
   guard error == nil else { return }
-  CometChatLocalize.setLocale(locale: Locale.preferredLanguages.first ?? "en")
+  let code = Locale.preferredLanguages.first?.split(separator: "-").first.map(String.init) ?? "en"
+  CometChatLocalize.set(locale: code)
 }
 ```
 
@@ -170,55 +205,67 @@ Each kit lets you register a custom language or override individual strings.
 CometChatLocalize.init({
   language: "es",
   fallbackLanguage: "en",
-  resources: {
-    es: {
-      CHAT: "Charla",
-      MESSAGES: "Mensajes",
-      // ... override only the strings you want
-    },
+  // FLAT key->value map for the ACTIVE language (NOT a nested `resources: { es: {...} }`
+  // object — LocalizationSettings has no `resources` field; it's silently ignored).
+  translationsForLanguage: {
+    "Chat": "Charla",
+    "Messages": "Mensajes",
+    // ... override only the strings you want, for the active language
   },
 });
+// To add overrides for additional languages, call CometChatLocalize.addTranslation({...}) per language.
 ```
 
+### React Native (v5) — `translations` prop on the provider
+
+```tsx
+<CometChatI18nProvider
+  selectedLanguage="es"
+  translations={{ es: { CHATS: "Charla", MESSAGES: "Mensajes" } }}
+>
+  {/* … */}
+</CometChatI18nProvider>
+```
+
+Add a brand-new language the same way: `translations={{ custom: { CHATS: "…" } }}` with `selectedLanguage="custom"`.
+
 ### Angular
 
-Positional second arg:
+Init with the object signature, then register custom strings via `addTranslation` (v5):
 
 ```ts
-CometChatLocalize.init("es", {
+CometChatLocalize.init({ language: "es" });
+CometChatLocalize.addTranslation({
   es: { CHAT: "Charla", MESSAGES: "Mensajes" },
 });
 ```
 
 ### Android
 
+The Android kit has **no string-override API** on `CometChatLocalize` (no `addStringResources`/`setStringResources`). Override individual strings the Android-native way — add a `values-es/strings.xml` with the kit's string keys to your app resources; Android resource resolution picks them up for the active locale.
+
 ```kotlin
-val customResources = mapOf(
-  "CHAT" to "Charla",
-  "MESSAGES" to "Mensajes",
-)
-CometChatLocalize.setLocale(Locale("es"))
-CometChatLocalize.addStringResources("es", customResources)   // verify symbol
+CometChatLocalize.setLocale(context, "es")   // selects the locale; string overrides live in res/values-es/
 ```
 
-The exact symbol for resource-override on Android varies by version — check the kit's published API surface.
-
 ### iOS
 
+iOS has **no `setStringResources` API** either. Override strings via your app's `Localizable.strings` (per-locale `.lproj`) using the kit's string keys; `set(locale:)` only selects the active locale.
+
 ```swift
-CometChatLocalize.setLocale(locale: "es")
-CometChatLocalize.setStringResources(["CHAT": "Charla"], for: "es")
+CometChatLocalize.set(locale: "es")   // overrides live in es.lproj/Localizable.strings
 ```
 
 ### Flutter
 
+Flutter has **no `CometChatLocalize.init`** — subclass the kit's `Translations` delegate to override or add strings, and register your delegate *before* `cc.Translations.delegate` in `MaterialApp.localizationsDelegates` (full recipe in `documentation/docs/ui-kit/flutter/localize.mdx`):
+
 ```dart
-CometChatLocalize.init(
-  language: 'es',
-  resources: {
-    'es': { 'CHAT': 'Charla', 'MESSAGES': 'Mensajes' },
-  },
-);
+class MyTranslations extends cc.Translations {
+  @override
+  String get chats => 'Charla';   // override individual getters
+}
+// register MyTranslationsDelegate() ahead of cc.Translations.delegate
 ```
 
 ---
@@ -262,11 +309,11 @@ if (isRTLLocale(language) && !I18nManager.isRTL) {
 Every kit falls back to English when a translation is missing for the active locale. Make this explicit:
 
 ```ts
-// React/RN/Flutter
-CometChatLocalize.init({ language: "es", fallbackLanguage: "en" });
+// React/RN/Angular (object signature) — fallbackLanguage is a settings field
+CometChatLocalize.init({ language: "es", fallbackLanguage: "en-US" });
 ```
 
-Angular and iOS don't have an explicit `fallbackLanguage` arg in their `init` / `setLocale` API — they hardcode English fallback internally. The skill doesn't try to override this.
+Angular v5's `LocalizationSettings` carries `fallbackLanguage` (verified in `cometchat-localize.ts` — defaults to `en-US`). RN's `<CometChatI18nProvider>` takes a `fallbackLanguage` prop. Flutter's `Translations` delegate and iOS's `set(locale:)` don't expose an explicit fallback arg — they fall back to English internally, so the skill doesn't try to override it there.
 
 ---
 
@@ -321,9 +368,23 @@ This is the workaround for kits that cache localized strings at first render.
 
 ---
 
+## Advanced init options + date/time formatting (web / JS family)
+
+`CometChatLocalize.init(settings)` (web, RN, Angular) accepts more than a language — the `LocalizationSettings` carries options the basic recipe omits (all verified in `cometchat-uikit-react-v6/src/resources/CometChatLocalize/cometchat-localize.ts`):
+
+- **`translationsForLanguage`** — inject custom string overrides at init (sugar for `addTranslation`).
+- **`missingKeyHandler`** — a callback invoked with any key that has no translation (log it, or return a fallback). Great for catching gaps in custom languages.
+- **`timezone`** — IANA zone string (e.g. `"America/New_York"`) used when the kit formats timestamps.
+
+**Date/time formatting** is controlled with `CalendarObject` (exported from the kit, `utils/CalendarObject.ts`) — pass one globally or per-component (e.g. a component's `lastActiveAtDateTimeFormat`-style prop) to control how the kit renders relative/absolute times. Query the docs MCP / `ui-kit/react/localize` for the full `CalendarObject` field list and the `flag_message_reason_*` / `message_composer_mention_*` translation-key conventions.
+
+> These are web/JS-family details. Native families (Android/iOS/Flutter) localize through their own resource/string mechanisms — see the per-family `-core`/`-troubleshooting` skills.
+
+---
+
 ## Anti-patterns
 
-1. **Calling `init` with the wrong signature.** Object instead of positional on Angular, vice-versa on React. The audit pass catches this — don't ship without verifying.
+1. **Using the wrong localization surface for the family.** Web + **Angular v5** take `CometChatLocalize.init({ language })` (object); **React Native v5** uses `<CometChatI18nProvider>` + `useCometChatTranslation` (NO `CometChatLocalize.init`); **Android** uses `CometChatLocalize.setLocale(context, "es")`; **iOS** uses `CometChatLocalize.set(locale: "es")`; **Flutter** has no `CometChatLocalize` — register the kit's `Translations` delegate. The legacy positional `init("es")` only ever applied to Angular **v4**. Verify against the installed package's types if unsure.
 2. **Setting locale before kit init.** Some kits ignore the early call. Always sequence: kit init → localize init.
 3. **No fallback language on web/RN/Flutter.** Missing translations show as raw keys (`CHAT_HEADER_TITLE` etc.) instead of English fallback.
 4. **`document.dir` not synced with locale on web.** RTL languages render LTR — broken layout.

package/skills/cometchat-ios/SKILL.md

@@ -2,13 +2,14 @@
 name: cometchat-ios
 description: Entry-point for CometChat iOS UI Kit integration in any Swift/iOS project. Detects the project type, gathers requirements through an interactive conversation, and writes production-quality integration code for UIKit and SwiftUI applications.
 license: "MIT"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat dispatcher entry ios swift uikit swiftui chat messaging"
 ---
 
+> **Ground truth:** `CometChatUIKitSwift ~> 5` (+ `CometChatCallsSDK ~> 5`) — Pods/SPM `.swiftinterface` + `ui-kit/ios`. **Official docs:** https://www.cometchat.com/docs/ui-kit/ios/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Use this skill when
 
 The user wants to add CometChat to any iOS project. Trigger phrases:
@@ -76,7 +77,8 @@ First, check for iOS project indicators:
 Store this mental map — you'll use it throughout the conversation.
 
 **Compatibility baselines:**
-- iOS 13+ required for CometChat UI Kit
+- iOS 13+ required for CometChat UI Kit (CometChatSDK floor is iOS 11)
+- **iOS 16+ required if you use calling** — `CometChatCallsSDK` 5.x has a deployment target of iOS 16.0; a project targeting iOS 13 will fail to link the Calls SDK
 - Swift 5.0+ required
 - Xcode 14+ recommended