of slugs. * `[ 'activation-welcome' ]`, `[ 'openstation-rebrand' ]`, etc. * Slug values pass through `sanitize_key()` and the list is capped * at 64 entries so a runaway client cannot bloat user-meta * indefinitely. * * @package OpenStation */ defined( 'ABSPATH' ) || exit; /** * User meta key — see file header for shape. * * The VALUE keeps its pre-rebrand spelling on purpose: it is a * persisted or externally-visible identifier, so renaming it would * orphan data already written by live installs (or break a live * URL). The mismatch between this constant's name and its value is * deliberate — it is NOT a half-finished rename. */ const OPENSTATION_SEEN_INTROS_META_KEY = 'desktop_mode_seen_intros'; /** Hard cap so a malicious client cannot grow the list unbounded. */ const OPENSTATION_SEEN_INTROS_MAX = 64; /** * Returns the list of intro slugs the user has dismissed. * * @param int $user_id User ID. * @return string[] Sanitized list (may be empty). */ function openstation_get_seen_intros( $user_id ) { $user_id = (int) $user_id; if ( $user_id <= 0 ) { return array(); } $raw = get_user_meta( $user_id, OPENSTATION_SEEN_INTROS_META_KEY, true ); if ( ! is_array( $raw ) ) { return array(); } return openstation_sanitize_seen_intros( $raw ); } /** * Whether the user has already dismissed the given intro. * * @param int $user_id User ID. * @param string $slug Intro slug (e.g. `'posts'`). * @return bool */ function openstation_has_seen_intro( $user_id, $slug ) { $slug = sanitize_key( (string) $slug ); if ( '' === $slug ) { return false; } return in_array( $slug, openstation_get_seen_intros( $user_id ), true ); } /** * Adds a slug to the user's seen-intros list. * * Idempotent — re-marking an already-seen intro is a no-op that * still returns true. A slug that supersedes others * ({@see openstation_seen_intros_superseded_by()}) removes them first. * * @param int $user_id User ID. * @param string $slug Intro slug. * @return bool True on successful write (or no-op), false otherwise. */ function openstation_mark_intro_seen( $user_id, $slug ) { $user_id = (int) $user_id; $slug = sanitize_key( (string) $slug ); if ( $user_id <= 0 || '' === $slug ) { return false; } $current = openstation_get_seen_intros( $user_id ); $kept = array_values( array_diff( $current, openstation_seen_intros_superseded_by( $slug ) ) ); if ( in_array( $slug, $kept, true ) && count( $kept ) === count( $current ) ) { return true; } if ( ! in_array( $slug, $kept, true ) ) { $kept[] = $slug; } $kept = array_slice( $kept, 0, OPENSTATION_SEEN_INTROS_MAX ); return false !== update_user_meta( $user_id, OPENSTATION_SEEN_INTROS_META_KEY, $kept ); } /** * Slugs a newly recorded one makes obsolete: facts where only the * latest counts, which an append-only list cannot otherwise express. * * The shell tour's two outcomes are the one pair. A run ends skipped * or finished, and the relaunch icon asks about the LATEST run: kept * side by side, one finished run long ago hid the icon after every * skip that came later. The strings mirror the constants in * `includes/first-run/shell-tour.php`, which loads after this file. * * @param string $slug The slug being recorded. * @return string[] Slugs it replaces. */ function openstation_seen_intros_superseded_by( $slug ) { $pairs = array( 'shell-tour-skipped' => array( 'shell-tour-done' ), 'shell-tour-done' => array( 'shell-tour-skipped' ), ); return isset( $pairs[ $slug ] ) ? $pairs[ $slug ] : array(); } /** * Wipes every seen-intro entry for the user. Used by the OS * Settings → Features "Reset what's-new dialogs" button. * * @param int $user_id User ID. * @return bool True on success. */ function openstation_clear_seen_intros( $user_id ) { $user_id = (int) $user_id; if ( $user_id <= 0 ) { return false; } return (bool) delete_user_meta( $user_id, OPENSTATION_SEEN_INTROS_META_KEY ); } /** * Coerces a raw payload to a clean list of slugs. * * @param mixed $raw Raw value. * @return string[] */ function openstation_sanitize_seen_intros( $raw ) { if ( ! is_array( $raw ) ) { return array(); } $out = array(); foreach ( $raw as $entry ) { if ( ! is_string( $entry ) ) { continue; } $slug = sanitize_key( $entry ); if ( '' === $slug ) { continue; } $out[] = $slug; } return array_slice( array_values( array_unique( $out ) ), 0, OPENSTATION_SEEN_INTROS_MAX ); } /** * Registers REST routes for the seen-intros surface. * * Routes: * POST /desktop-mode/v1/intros/seen body: { slug: string } * DELETE /desktop-mode/v1/intros no body — clears the list * * Both return the post-mutation list so the client can refresh its * local snapshot without a follow-up GET. */ function openstation_register_seen_intros_routes() { register_rest_route( 'desktop-mode/v1', '/intros/seen', array( 'methods' => WP_REST_Server::CREATABLE, 'callback' => 'openstation_rest_mark_intro_seen', 'permission_callback' => 'openstation_rest_seen_intros_permission', 'args' => array( 'slug' => array( 'required' => true, 'type' => 'string', ), ), ) ); register_rest_route( 'desktop-mode/v1', '/intros', array( 'methods' => WP_REST_Server::DELETABLE, 'callback' => 'openstation_rest_clear_seen_intros', 'permission_callback' => 'openstation_rest_seen_intros_permission', ) ); } add_action( 'rest_api_init', 'openstation_register_seen_intros_routes' ); /** * The intro slugs whose dismissal is accepted from an account that has * NOT enabled OpenStation. * * Exactly the intros that render in the classic admin while the shell * is off: the welcome dialog and the activation nudge. Everything else * is shown inside the shell and keeps the strict gate. Adding a slug * here is adding a classic-admin surface; the allowlist is the review * point, so keep it a literal list. * * @return string[] */ function openstation_seen_intros_classic_admin_slugs() { $slugs = array(); if ( defined( 'OPENSTATION_WELCOME_INTRO_SLUG' ) ) { $slugs[] = OPENSTATION_WELCOME_INTRO_SLUG; } if ( defined( 'OPENSTATION_ACTIVATION_NUDGE_INTRO_SLUG' ) ) { $slugs[] = OPENSTATION_ACTIVATION_NUDGE_INTRO_SLUG; } return $slugs; } /** * Permission gate for the seen-intros routes. * * In-shell announcements (the rebrand notice, and anything a plugin * registers) are only ever shown to a user who has already entered * OpenStation, so they keep the strict * {@see openstation_rest_require_enabled()} gate — `read` alone is * insufficient (every role, Subscriber included, carries `read`). * * The exceptions are the classic-admin intros * ({@see openstation_seen_intros_classic_admin_slugs()}): the first-run * welcome dialog and the activation nudge both render in the *classic* * admin precisely when OpenStation is NOT enabled, which is the only * state they ever appear in. Gating their dismissal behind * `openstation_rest_require_enabled()` would make the dismissal POST * return 403 every time, so the slug could never be recorded as seen and * the dialog / notice re-rendered on every classic-admin page load. We * therefore let those slugs through for any logged-in `read`-capable * account (the exact audience they are shown to); writing one's own * dismissal flag carries no privileged surface. The DELETE /intros route * ("Reset what's-new dialogs") carries no slug and keeps the strict gate. * * @param WP_REST_Request $request The REST request. * @return true|WP_Error */ function openstation_rest_seen_intros_permission( WP_REST_Request $request ) { $slug = sanitize_key( (string) $request->get_param( 'slug' ) ); if ( '' !== $slug && in_array( $slug, openstation_seen_intros_classic_admin_slugs(), true ) ) { if ( ! is_user_logged_in() ) { return new WP_Error( 'rest_forbidden', __( 'Authentication required.', 'desktop-mode' ), array( 'status' => 401 ) ); } if ( ! current_user_can( 'read' ) ) { return new WP_Error( 'rest_forbidden', __( 'You are not allowed to do that.', 'desktop-mode' ), array( 'status' => 403 ) ); } return true; } return openstation_rest_require_enabled(); } /** * REST handler for `POST /desktop-mode/v1/intros/seen`. * * @param WP_REST_Request $request REST request. * @return WP_REST_Response|WP_Error */ function openstation_rest_mark_intro_seen( WP_REST_Request $request ) { $user_id = get_current_user_id(); $slug = sanitize_key( (string) $request->get_param( 'slug' ) ); if ( '' === $slug ) { return new WP_Error( 'openstation_invalid_intro_slug', __( 'The `slug` parameter must be a non-empty string.', 'desktop-mode' ), array( 'status' => 400 ) ); } openstation_mark_intro_seen( $user_id, $slug ); return rest_ensure_response( array( 'seenIntros' => openstation_get_seen_intros( $user_id ) ) ); } /** * REST handler for `DELETE /desktop-mode/v1/intros`. * * @return WP_REST_Response */ function openstation_rest_clear_seen_intros() { $user_id = get_current_user_id(); openstation_clear_seen_intros( $user_id ); return rest_ensure_response( array( 'seenIntros' => openstation_get_seen_intros( $user_id ) ) ); }