@risacakep/risayap 0.0.0-stage → 7.0.0-rc25.7

package/CLARISSA-BAILEYS-RC25.md

@@ -0,0 +1,168 @@
+# Clarissa Baileys RC25 — Developer Guide
+
+**Package:** `@risacakep/risayap`  
+**Inspected package version:** `7.0.0-rc25.4`  
+**Documentation:** <https://clarissa.github.io/clarissa-baileys-docs/>  
+**Status:** Release candidate; experimental APIs are not guaranteed to work across all WhatsApp clients or server-side capabilities.
+
+Clarissa Baileys is an unofficial TypeScript toolkit based on the WhiskeySockets Baileys project, with additional Clarissa extensions. It is not affiliated with WhatsApp or Meta.
+
+## 1. Installation
+
+The project currently distributes its RC25 prereleases through the npm `next` dist-tag. Install that channel explicitly:
+
+```bash
+npm install @risacakep/risayap@next
+```
+
+The `latest` dist-tag is maintained separately. Do not omit `@next` when you intend to install the RC25 prerelease channel.
+
+Use Node.js 20 or newer, matching the compatibility target documented by this project. Keep your authentication data private and never commit session credentials to a public repository.
+
+## 2. Basic connection pattern
+
+The package exports `makeWASocket` as both the default export and a named export. Authentication helpers are re-exported from the package entry point.
+
+```ts
+import makeWASocket, {
+  useMultiFileAuthState,
+} from "@risacakep/risayap";
+
+async function main() {
+  const { state, saveCreds } = await useMultiFileAuthState("./auth");
+  const socket = makeWASocket({ auth: state });
+
+  socket.ev.on("creds.update", saveCreds);
+  return socket;
+}
+
+void main();
+```
+
+This is a minimal connection pattern, not a complete production deployment. Review the upstream Baileys guidance and the examples shipped with the source before deploying a long-running service. Add appropriate logging, reconnect handling, shutdown handling, and secure storage for credentials in your own application.
+
+## 3. Package entry points and exports
+
+The package metadata identifies `lib/index.js` as the JavaScript entry point and `lib/index.d.ts` as the TypeScript declaration entry point.
+
+The root entry point exports the default and named `makeWASocket` factory, WAProto exports, shared utilities, types, defaults, and these Clarissa-facing modules:
+
+- `MessageBuilder`
+- Advanced extensions
+- Experimental extensions
+
+The root entry point also invokes the Clarissa terminal welcome display when it is imported.
+
+## 4. MessageBuilder toolkit
+
+The MessageBuilder module exports the following principal classes and helpers:
+
+| Export | Purpose |
+|:--|:--|
+| `Button` | Button-oriented message builder |
+| `ButtonV2` | Newer button builder interface |
+| `Carousel` | Carousel message builder |
+| `AIRich` | Rich/AI-oriented message builder |
+| `Toolkit` | Deterministic helper utilities |
+| `MessageBuilder` | Object grouping the builders and helper functions |
+| `MB` | Alias for `MessageBuilder` |
+| `checkNativeFlowButtons` | Native-flow button validation |
+| `isWebSupportedNativeFlowButton` | Checks web-supported native-flow button names |
+| `readRichMessage` | Reads rich-message content |
+| `readSocialPreview` | Reads social-preview content |
+
+The precise constructor options and supported payload shapes are defined by the installed TypeScript declarations. Consult those declarations rather than assuming that all interactive formats are accepted by every WhatsApp client.
+
+## 5. Advanced extensions
+
+The advanced module includes the following exported capabilities:
+
+### Message and content helpers
+
+- `unwrapMessage`
+- `readRichMessage`
+- `readSocialPreview`
+- `normalizeUserJid`
+- `buildButtonsMessage`
+- `buildListMessage`
+- `sendClassicMessage`
+- `sendAlbum`
+- `richLink`
+- `inspectMessageContent`
+
+### Socket and in-memory helpers
+
+- `attachAdvancedSocketMethods`
+- `makeInMemoryStore`
+
+### Authentication adapters
+
+- `useSingleFileAuthState`
+- `useSqliteAuthState`
+- `usePostgresAuthState`
+- `useMySQLAuthState`
+- `useMongoAuthState`
+- `useRedisAuthState`
+- `useCacheManagerAuthState`
+- `useNekoDBAuth`
+- `useAdapterAuthState`
+- `makeCacheManagerAuthState`
+
+Database-specific helpers expect compatible database clients, pools, or adapter objects supplied by the application. Install and configure the corresponding database driver separately when required; these adapters do not mean that every database server or driver is bundled with Clarissa.
+
+### Media helpers
+
+- `probeMedia`
+- `convertToWhatsAppVideo`
+- `convertToOpusAudio`
+- `getVideoThumbnail`
+- `resizeImage`
+- `getMp4Duration`
+
+Review the TypeScript declarations and your environment requirements before using media conversion helpers. Availability can depend on external media tooling and platform support.
+
+## 6. Experimental extensions
+
+The experimental module contains APIs for newer or less-established message structures and integrations. The RC25 changelog lists additions including:
+
+- WebUI and A2UI message builders and socket helpers
+- Rich Menu builders and helpers
+- Image-poll message helpers
+- Scheduled-message primitives and helpers
+- Question, status, Add Yours, comment, and status-link-preview helpers
+- Newsletter invitation helpers
+- Scheduled-call message helpers
+- Poll-add-option helpers
+- An explicit VoIP client adapter contract
+
+Some named exports visible in the source include `A2UI`, `buildWebuiMessage`, `sendInlineWebUI`, `sendA2UIWidget`, `buildRichMenuMessage`, `sendRichMenu`, `sendImagePoll`, `sendScheduledMessage`, `sendPollAddOption`, `sendNewsletterAdminInvite`, `sendNewsletterFollowerInvite`, and `makeVoipClient`.
+
+**Experimental means experimental.** Server support, WhatsApp client versions, account eligibility, payload restrictions, and protocol changes may affect behavior. Test with a separate account and non-critical data. Do not promise delivery or universal compatibility for these message types.
+
+The VoIP feature is exposed through an adapter contract; the VoIP engine is not bundled by this package. Applications must provide a compatible adapter/engine where required.
+
+## 7. Source examples
+
+The source repository contains:
+
+- `Example/example.ts` — standard socket example
+- `Example/experimental-features.ts` — examples of selected experimental APIs
+
+Treat these files and the installed `.d.ts` declarations as the reference for exact call signatures. Example files in the source repository are not necessarily included in the published npm tarball.
+
+## 8. Release and compatibility notes
+
+- `7.0.0-rc25.4` is a prerelease, not a stable release.
+- Install the RC25 channel with `@next` explicitly.
+- Interactive and experimental protocol features may change between prereleases.
+- Review `CHANGELOG.md` for release-by-release notes in the source repository.
+- Keep authentication state secure and maintain backups before changing persistence adapters.
+- Do not generate or modify WAProto files unless you intentionally maintain the protocol schema and understand the consequences.
+
+## 9. Credits and disclaimer
+
+Clarissa Baileys is derived from [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys). The project retains the upstream MIT license notice in its `LICENSE` file. Preserve upstream copyright and license notices when redistributing applicable source portions.
+
+This is an unofficial community project and is not affiliated with WhatsApp or Meta. WhatsApp is a trademark of its respective owner.
+
+For project documentation, see <https://clarissa.github.io/clarissa-baileys-docs/>.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rajeh Taher/WhiskeySockets
+
+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/MIGRASI-CLARISSA-BAILEYS-RC25.md

@@ -0,0 +1,102 @@
+# Migration Guide — Clarissa Baileys RC25
+
+This guide covers moving an application to the Clarissa Baileys RC25 prerelease channel. The inspected package version for this guide is `7.0.0-rc25.4`.
+
+> RC25 is a prerelease. Review the changelog and validate your application in a controlled environment before upgrading production workloads.
+
+## 1. Install the intended release channel
+
+The project uses npm dist-tags to separate release channels. Install RC25 explicitly:
+
+```bash
+npm install @risacakep/risayap@next
+```
+
+Do not assume that `npm install @risacakep/risayap` selects RC25. The project may maintain a different version under the `latest` tag.
+
+## 2. Update package imports deliberately
+
+Use the Clarissa package name in application imports:
+
+```ts
+import makeWASocket, {
+  MessageBuilder,
+  A2UI,
+  sendImagePoll,
+  sendScheduledMessage,
+} from "@risacakep/risayap";
+```
+
+Only import symbols that your application actually uses. Check the installed `lib/index.d.ts` for the exact exported names and call signatures of the version you installed. Do not copy source-relative imports such as `../src` from repository examples into an installed application.
+
+## 3. Preserve and protect authentication state
+
+Before upgrading:
+
+1. Stop the running client cleanly.
+2. Make a private backup of the existing authentication directory or database.
+3. Keep credentials out of source control, logs, screenshots, and public issue reports.
+4. Upgrade the package without deleting the existing auth state.
+5. Test reconnection with a controlled account before deploying the updated application.
+
+Changing the package version does not itself require deleting or regenerating authentication credentials. Do not delete auth data as a generic troubleshooting step.
+
+## 4. Review custom extensions separately
+
+RC25 exposes additional functionality in three broad areas:
+
+### MessageBuilder
+
+The current source exports `Button`, `ButtonV2`, `Carousel`, `AIRich`, `Toolkit`, `MessageBuilder`, and `MB`, along with native-flow validation and rich-message reading helpers.
+
+Review the declaration signatures for your exact builder usage. Do not assume a payload from one builder version is interchangeable with another.
+
+### Advanced extensions
+
+The advanced module includes album and classic interactive-message helpers, rich-link helpers, message readers, in-memory storage, authentication adapters, and media utilities.
+
+If you use database-backed auth adapters, confirm that your application passes a compatible client, pool, or adapter. Database drivers and services may need to be installed and configured separately.
+
+### Experimental extensions
+
+RC25 includes WebUI/A2UI, Rich Menu, image poll, scheduled-message, modern status/question, newsletter, scheduled-call, and poll-add-option helpers. These are experimental and may be affected by protocol or client-side support changes.
+
+Enable experimental functionality only where needed. Test it independently from your normal message flow and maintain a fallback path for unsupported clients.
+
+## 5. VoIP adapter contract
+
+The RC25 changelog describes an explicit VoIP adapter contract and states that the engine is not bundled. Applications that use this interface must supply and maintain a compatible adapter/engine. Do not treat the presence of `makeVoipClient` as proof that a working VoIP engine is installed.
+
+## 6. Validate after the upgrade
+
+Recommended application-level checks:
+
+- Confirm that the application resolves `@risacakep/risayap` to the expected prerelease version.
+- Confirm that the existing auth state can be loaded and credentials can be saved.
+- Confirm basic connection and ordinary send/receive flows.
+- Exercise each Clarissa extension used by the application independently.
+- Test media helpers in the target operating environment.
+- Test experimental features only with a separate or non-critical account.
+- Monitor logs for protocol, authentication, or dependency errors.
+
+Do not infer that every RC25 feature has been fully validated merely because it is exported. The RC25 changelog itself records that the source-level integration was not fully type-checked or runtime-tested at the time of that changelog entry.
+
+## 7. Rollback
+
+If the prerelease causes an application regression:
+
+1. Stop the application.
+2. Restore the previously recorded package version in your project manifest/lockfile.
+3. Reinstall dependencies from that known-good lockfile.
+4. Restore the auth-state backup only if the application has actually damaged or migrated it; do not overwrite a valid, current session without reason.
+5. Re-test ordinary connection and messaging flows.
+
+Record the exact previous package version before upgrading so rollback is deterministic.
+
+## 8. Release notes and support references
+
+- Project documentation: <https://clarissa.github.io/clarissa-baileys-docs/>
+- npm package: <https://www.npmjs.com/package/@risacakep/risayap>
+- Upstream project: <https://github.com/WhiskeySockets/Baileys>
+
+For exact changes, consult the corresponding release entry in `CHANGELOG.md` in the source repository.