'; } public function description() { return __( 'Open a Help Scout conversation for each entry, with files attached.', 'fieldwren' ); } public function help() { return '

' . esc_html__( 'Help Scout → your profile → My Apps → Create My App (any redirect URL, e.g. your site). Copy the App ID and App Secret. Conversations are created as the user who owns the app.', 'fieldwren' ) . '

'; } public function credential_fields() { return array( 'app_id' => array( 'label' => __( 'App ID', 'fieldwren' ), 'type' => 'text', 'required' => true ), 'app_secret' => array( 'label' => __( 'App secret', 'fieldwren' ), 'type' => 'password', 'required' => true ), ); } protected function error_message( $body, $code ) { if ( is_array( $body ) && ! empty( $body['_embedded']['errors'] ) ) { $parts = array(); foreach ( (array) $body['_embedded']['errors'] as $e ) { $parts[] = trim( ( $e['path'] ?? '' ) . ' ' . ( $e['message'] ?? '' ) ); } return trim( ( $body['message'] ?? '' ) . ': ' . implode( '; ', $parts ), ': ' ); } return parent::error_message( $body, $code ); } /** @return string|\WP_Error Access token (client credentials, cached). */ private function token( array $creds = null ) { $c = null === $creds ? $this->creds() : $creds; $key = 'fwren_helpscout_at_' . md5( ( $c['app_id'] ?? '' ) . ( $c['app_secret'] ?? '' ) ); $hit = get_transient( $key ); if ( is_string( $hit ) && '' !== $hit ) { $this->secrets[] = $hit; return $hit; } $b = self::body( $this->http( 'POST', self::API . '/oauth2/token', array( 'form' => true, 'body' => array( 'grant_type' => 'client_credentials', 'client_id' => (string) ( $c['app_id'] ?? '' ), 'client_secret' => (string) ( $c['app_secret'] ?? '' ), ), ) ) ); if ( is_wp_error( $b ) ) { return $b; } if ( empty( $b['access_token'] ) ) { return new \WP_Error( 'fwren_helpscout', __( 'Help Scout did not return an access token.', 'fieldwren' ) ); } set_transient( $key, (string) $b['access_token'], max( 300, (int) ( $b['expires_in'] ?? 7200 ) - 600 ) ); $this->secrets[] = (string) $b['access_token']; return (string) $b['access_token']; } private function api( $method, $path, $body = null, array $creds = null ) { $t = $this->token( $creds ); if ( is_wp_error( $t ) ) { return $t; } $args = array( 'headers' => array( 'Authorization' => 'Bearer ' . $t ), 'timeout' => 60 ); if ( null !== $body ) { $args['body'] = $body; } return $this->http( $method, self::API . $path, $args ); } public function verify( array $creds ) { $this->secrets = $this->secret_values( $creds ); $b = self::body( $this->api( 'GET', '/users/me', null, $creds ) ); return is_wp_error( $b ) ? $b : (string) ( $b['email'] ?? '' ); } public function options( $source, array $settings ) { if ( 'mailboxes' === $source ) { $b = self::body( $this->api( 'GET', '/mailboxes' ) ); return is_wp_error( $b ) ? $b : self::pluck( $b['_embedded']['mailboxes'] ?? array(), 'id', 'name' ); } if ( 'users' === $source ) { $mb = (int) ( $settings['mailbox'] ?? 0 ); $b = self::body( $this->api( 'GET', '/users' . ( $mb ? '?mailbox=' . $mb : '' ) ) ); $out = array(); foreach ( is_wp_error( $b ) ? array() : (array) ( $b['_embedded']['users'] ?? array() ) as $u ) { $out[ (string) $u['id'] ] = trim( ( $u['firstName'] ?? '' ) . ' ' . ( $u['lastName'] ?? '' ) ) . ' <' . ( $u['email'] ?? '' ) . '>'; } return is_wp_error( $b ) ? $b : $out; } return parent::options( $source, $settings ); } public function feed_fields( $form_id ) { return array_merge( array( array( 'key' => 'mailbox', 'type' => 'select', 'source' => 'mailboxes', 'label' => __( 'Mailbox', 'fieldwren' ), 'required' => true ) ), $this->contact_fields( array( 'email', 'first_name', 'last_name' ) ), array( array( 'key' => 'subject', 'type' => 'text', 'label' => __( 'Subject', 'fieldwren' ), 'required' => true, 'default' => __( 'New submission: {form_title}', 'fieldwren' ) ), array( 'key' => 'body', 'type' => 'textarea', 'html' => true, 'rows' => 5, 'label' => __( 'Message', 'fieldwren' ), 'default' => '{all_data}', 'desc' => __( 'HTML allowed; {all_data} gives a table of the answers.', 'fieldwren' ) ), array( 'key' => 'tags', 'type' => 'text', 'label' => __( 'Tags', 'fieldwren' ), 'desc' => __( 'Comma separated; smartcodes allowed.', 'fieldwren' ) ), array( 'key' => 'status', 'type' => 'select', 'label' => __( 'Status', 'fieldwren' ), 'default' => 'active', 'no_empty' => true, 'options' => array( 'active' => __( 'Active', 'fieldwren' ), 'pending' => __( 'Pending', 'fieldwren' ), 'closed' => __( 'Closed', 'fieldwren' ) ) ), array( 'key' => 'assignee', 'type' => 'select', 'source' => 'users', 'depends' => array( 'mailbox' ), 'label' => __( 'Assign to', 'fieldwren' ) ), array( 'key' => 'attach', 'type' => 'toggle', 'label' => __( 'Attachments', 'fieldwren' ), 'text' => __( 'Attach uploaded files (each under 10 MB)', 'fieldwren' ), 'default' => true ), ) ); } public function process( array $feed, array $entry, array $values ) { $s = $feed['settings']; $c = $this->contact(); $err = $this->require_email( $c ); if ( $err ) { return $err; } $mailbox = (int) ( $s['mailbox'] ?? 0 ); if ( ! $mailbox ) { return new \WP_Error( 'fwren_helpscout', __( 'Choose a mailbox.', 'fieldwren' ) ); } $subject = $this->sval( 'subject' ); $text = $this->html_val( $s['body'] ?? '' ); $thread = array( 'type' => 'customer', 'customer' => array( 'email' => $c['email'] ), 'text' => '' !== $text ? $text : esc_html( $this->default_title() ), ); $skipped = array(); if ( ! empty( $s['attach'] ) ) { $total = 0; foreach ( $this->entry_files() as $f ) { if ( $f['size'] >= self::ATTACH_MAX || $total + $f['size'] > 4 * self::ATTACH_MAX ) { $skipped[] = $f['name']; continue; } $data = file_get_contents( $f['abs'] ); // phpcs:ignore WordPress.WP.AlternativeFunctions if ( false === $data ) { continue; } $total += $f['size']; $thread['attachments'][] = array( 'fileName' => $f['name'], 'mimeType' => $f['type'], 'data' => base64_encode( $data ) ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions } } $conv = array( 'subject' => self::cut( '' !== $subject ? $subject : $this->default_title(), 250 ), 'customer' => array_filter( array( 'email' => $c['email'], 'firstName' => $c['first_name'], 'lastName' => $c['last_name'] ), 'strlen' ), 'mailboxId' => $mailbox, 'type' => 'email', 'status' => in_array( $s['status'] ?? '', array( 'active', 'pending', 'closed' ), true ) ? $s['status'] : 'active', 'threads' => array( $thread ), ); $tags = $this->list_of( $s['tags'] ?? '' ); if ( $tags ) { $conv['tags'] = $tags; } if ( ! empty( $s['assignee'] ) ) { $conv['assignTo'] = (int) $s['assignee']; } $res = $this->api( 'POST', '/conversations', $conv ); if ( is_wp_error( $res ) ) { return $res; } $id = $res['headers']['resource-id'] ?? ''; $id = is_array( $id ) ? end( $id ) : (string) $id; /* translators: %s conversation id */ $msg = sprintf( __( 'Conversation #%s created.', 'fieldwren' ), $id ); if ( $skipped ) { /* translators: %s files */ $msg .= ' ' . sprintf( __( 'Not attached (too large): %s', 'fieldwren' ), implode( ', ', $skipped ) ); } return $msg; } }