Changeset 3771693 for joinotify/trunk/admin/src/Core/Functions.php

Timestamp:

10/28/2026 09:22:17 PM (7 days ago)

Author:

meumouse

Message:

Release 2.6.0

File:

• joinotify/trunk/admin/src/Core/Functions.php (modified) (4 diffs)

joinotify/trunk/admin/src/Core/Functions.php

@@ -8 +8 @@
 
 use MeuMouse\Joinotify\Api\Transport;
+use MeuMouse\Joinotify\Api\Contact_Window;
+use MeuMouse\Joinotify\Api\Template_Repository;
 use MeuMouse\Joinotify\Api\Extensions;
 use MeuMouse\Joinotify\Admin\Admin;
@@ -16 +18 @@
 use MeuMouse\Joinotify\Core\Message_History;
 use MeuMouse\Joinotify\Core\Logger;
+use MeuMouse\Joinotify\Core\Workflow_Processor;
 use MeuMouse\Joinotify\Notifications\Channel_Manager;
 use MeuMouse\Joinotify\Notifications\Notification_Message;
@@ -80 +83 @@
 
    return $response;
+}
+
+
+/**
+ * Send an approved WhatsApp template and say what happened.
+ *
+ * Meant for integrations that need the outcome right away — a login code, a
+ * transactional notice sent from another plugin. The send goes through the
+ * same path as the workflow actions (sender check, one-line parameters, message
+ * history, debug log), but in a single attempt by default: a code that expires
+ * in minutes is worse than useless when a retry delivers it an hour later.
+ *
+ * `$args`:
+ * - `sender` — origin number in digits; defaults to the first connected sender.
+ * - `queue_on_failure` — put a send refused for a transient reason (rate limit,
+ *   API unavailable) in the retry queue; default false.
+ * - `context` — dispatch context for the message history while this send runs,
+ *   e.g. `array( 'source' => 'otp' )`, which masks the template values (login
+ *   codes) before they are stored. The context set before the call is restored.
+ *
+ * @since 2.6.0
+ * @param string $receiver      | Recipient phone, with or without the country code.
+ * @param string $template_name | Approved template name.
+ * @param string $language      | Template language code (e.g. pt_BR).
+ * @param array  $components    | Meta components with the parameters already resolved.
+ * @param array  $args          | Options: sender, queue_on_failure, context.
+ * @return array{message_id:string,status:string}|WP_Error `status` is `sent`, or `queued`
+ *         (with an empty `message_id`) when `queue_on_failure` put it in the retry queue. The
+ *         error data carries `status` (HTTP status to answer with), `response_code` (the
+ *         Joinotify API's, 0 when not reached), `reason`, `detail`, `meta_code`, `retryable`
+ *         and, for a 429, `retry_after` in seconds.
+ */
+function joinotify_send_whatsapp_template( string $receiver, string $template_name, string $language = 'pt_BR', array $components = array(), array $args = array() ) {
+        $args = wp_parse_args( $args, array(
+                'sender' => '',
+                'queue_on_failure' => false,
+                'context' => array(),
+        ) );
+
+        $sender = is_scalar( $args['sender'] ) ? preg_replace( '/\D/', '', (string) $args['sender'] ) : '';
+
+        if ( '' === $sender ) {
+                $sender = preg_replace( '/\D/', '', (string) joinotify_get_first_sender() );
+        }
+
+        if ( '' === $sender ) {
+                return new WP_Error( 'joinotify_no_sender', __( 'No WhatsApp number is connected to Joinotify to send from.', 'joinotify' ), array(
+                        'status' => 503,
+                        'response_code' => 0,
+                        'reason' => 'no_sender',
+                        'detail' => '',
+                        'meta_code' => 0,
+                        'retryable' => false,
+                ) );
+        }
+
+        $context = is_array( $args['context'] ) ? $args['context'] : array();
+        $previous_context = Message_History::get_context();
+
+        if ( ! empty( $context ) ) {
+                Message_History::set_context( $context );
+        }
+
+        try {
+                $details = Transport::send_message_template( $sender, $receiver, $template_name, $language, $components, 0, (bool) $args['queue_on_failure'], true );
+        } finally {
+                if ( ! empty( $context ) ) {
+                        Message_History::set_context( $previous_context );
+                }
+        }
+
+        return Transport::template_send_result( $details );
+}
+
+
+/**
+ * List the WhatsApp message templates of the connected account.
+ *
+ * Served from a 15-minute local cache of the platform's own mirror; `force`
+ * asks the platform to read Meta again. Every template says what it expects:
+ * `header_format` (`TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT`, `LOCATION` or empty),
+ * `buttons` and `variables`, one entry per value in the order Meta wants them
+ * (`component`, `sub_type`, `index`, `key`, `label`, `format` and, for a URL
+ * button, the button's `url` with its token). A value with no token has an
+ * empty `key`: a media header (`format` `image`, `video`, `document`), a
+ * copy-code button (`sub_type` `copy_code`) or the login-code button of an
+ * AUTHENTICATION template (`format` `otp`). A location header is four
+ * variables (`format` `location`), an expiring offer one `limited_time_offer`
+ * variable, and the variables of a carousel card carry its position in `card`
+ * (-1 outside a carousel), as `cards` describes each card.
+ *
+ * @since 2.6.0
+ * @param array $args | Optional `status`, `waba_id` and `force`.
+ * @return array|WP_Error `templates`, `total`, `waba_id`, `synced_at`, `stale`, `sync_error`.
+ */
+function joinotify_get_whatsapp_templates( array $args = array() ) {
+        return Template_Repository::get_templates( $args );
+}
+
+
+/**
+ * Find one WhatsApp message template by name.
+ *
+ * Reads the local copy first and loads the listing once when nothing local
+ * knows the template, so it is safe on a send path.
+ *
+ * @since 2.6.0
+ * @param string $name     | Template name as approved on Meta.
+ * @param string $language | Language to prefer (e.g. pt_BR); empty for any.
+ * @return array|null Normalized template (as in joinotify_get_whatsapp_templates()), or null.
+ */
+function joinotify_get_whatsapp_template( string $name, string $language = '' ) {
+        return Template_Repository::find_or_fetch( $name, $language );
+}
+
+
+/**
+ * Pack template values already resolved into the `components` of a template send.
+ *
+ * Each variable is an entry of the template's `variables` with its `value`
+ * set; a media header is a `header` entry with `format` (`image`, `video`,
+ * `document`) and the file link (or a Meta media id) as its value, and a
+ * `copy_code` button entry takes the coupon. Location, offer expiration and
+ * carousel card entries are packed as their template lists them (see
+ * joinotify_get_whatsapp_templates()). Values are not run through the
+ * Joinotify placeholders: they go out as given, brought to the one line Meta
+ * accepts, and named variables carry their `parameter_name`.
+ *
+ * @since 2.6.0
+ * @param array $variables | Variables with their resolved `value`.
+ * @return array Components for joinotify_send_whatsapp_template().
+ */
+function joinotify_build_whatsapp_template_components( array $variables ) {
+        return Workflow_Processor::components_from_values( $variables );
+}
+
+
+/**
+ * Write the text a recipient reads for a template and its components.
+ *
+ * Header, body and footer with the values in place; a template the site does
+ * not know is described by its name and values instead.
+ *
+ * @since 2.6.0
+ * @param string $name       | Template name.
+ * @param string $language   | Template language code.
+ * @param array  $components | Components as sent.
+ * @return string
+ */
+function joinotify_render_whatsapp_template( string $name, string $language = '', array $components = array() ) {
+        $rendered = Template_Repository::render( $name, $language, $components );
+
+        return (string) ( $rendered['text'] ?? '' );
+}
+
+
+/**
+ * Read the customer service window of a contact on one of the account numbers.
+ *
+ * Free text and media reach a contact only while the window opened by the
+ * contact's last message is open (24 hours, 72 hours after a click-to-WhatsApp
+ * ad); outside it only an approved template goes out. The platform answers for
+ * the window, webhooks or not. `unknown` means it could not be asked — not
+ * connected, unreachable, rate limited — so a caller that sends a template on
+ * anything but `open` is always right.
+ *
+ * @since 2.6.0
+ * @param string $phone  | Contact phone with the country code.
+ * @param string $sender | Origin number in digits; empty uses the first connected sender.
+ * @return array{state:string,expires_at:string,remaining_seconds:int}
+ */
+function joinotify_get_whatsapp_window( string $phone, string $sender = '' ) {
+        return Contact_Window::get( $phone, $sender );
 }
 
@@ -423 +599 @@
  * Get a Joinotify plugin setting value.
  *
- * @since 2.0.0
+ * The Joinotify API key (`whatsapp_cloud_api_token`) is stored sealed since 2.6.0
+ * and may come from the `JOINOTIFY_CLOUD_API_TOKEN` constant, so it is answered
+ * through Helpers::cloud_api_token(), in the clear, as before.
+ *
+ * @since 2.0.0
+ * @version 2.6.0
  * @param string $key | Setting key.
  * @return mixed Setting value, or false when the key is not set.
  */
 function joinotify_get_setting( $key ) {
+        if ( 'whatsapp_cloud_api_token' === $key ) {
+                if ( false === Admin::get_setting( $key ) && ! Helpers::cloud_api_token_locked() ) {
+                        return false;
+                }
+
+                return Helpers::cloud_api_token();
+        }
+
         return Admin::get_setting( $key );
 }