Module: Studio

Defined in:
lib/studio.rb,
lib/studio/s3.rb,
lib/studio/email.rb,
lib/studio/engine.rb,
lib/studio/version.rb,
lib/studio/color_scale.rb,
lib/studio/email_smoke.rb,
lib/studio/image_cache.rb,
lib/studio/ui_primitives.rb,
lib/studio/mail_transport.rb,
lib/studio/theme_resolver.rb,
lib/studio/username_generator.rb,
app/models/studio/email_delivery.rb,
app/jobs/studio/email_delivery_job.rb,
app/controllers/concerns/studio/admin_models.rb,
app/controllers/concerns/studio/impersonation.rb,
app/controllers/concerns/studio/error_handling.rb,
app/controllers/studio/local_emails_controller.rb

Defined Under Namespace

Modules: AdminModels, ColorScale, Email, ErrorHandling, ImageCache, Impersonation, S3, UiPrimitives Classes: EmailDelivery, EmailDeliveryJob, EmailSmoke, Engine, LocalEmailsController, MailTransport, S3ConfigError, ThemeResolver, UserContractError, UsernameGenerator

Constant Summary collapse

REQUIRED_USER_INSTANCE_METHODS =

Only methods that consumers must explicitly define are checked here. Column accessors (#email, #name, #role) are NOT validated because ActiveRecord defines them lazily — they don’t appear on ‘.instance_methods` until the schema is introspected (typically first record access). Missing columns are caught by the User table schema, not by this validator.

%i[admin? display_name].freeze
REQUIRED_USER_CLASS_METHODS = 
%i[find_by].freeze
PASSWORD_USER_INSTANCE_METHODS =

#authenticate is only required when email+password sign-in is enabled. Passwordless apps (the default) never call it.

%i[authenticate].freeze
VERSION = 
"0.6.2"

Class Method Summary collapse

Class Method Details

.auth_method?(method) ⇒ Boolean

True when the given sign-in method is enabled for this app.

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/studio.rb', line 134

def self.auth_method?(method)
  auth_methods.include?(method.to_sym)
end

.configure {|_self| ... } ⇒ Object

Yields:

  • (_self)

Yield Parameters:

  • _self (Studio) —

    the object that the method was called on



99
100
101
 
# File 'lib/studio.rb', line 99

def self.configure
  yield self
end

.env_truthy?(value) ⇒ Boolean

Returns:

  • (Boolean) 


216
217
218
 
# File 'lib/studio.rb', line 216

def self.env_truthy?(value)
  %w[1 true yes on].include?(value.to_s.strip.downcase)
end

.env_value(env, key) ⇒ Object 



128
129
130
131
 
# File 'lib/studio.rb', line 128

def self.env_value(env, key)
  value = env[key]
  value if value && !value.to_s.strip.empty?
end

.local_email_capture? ⇒ Boolean

Returns:

  • (Boolean) 


138
139
140
141
142
143
 
# File 'lib/studio.rb', line 138

def self.local_email_capture?
  return false if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
  return !!local_email_capture unless local_email_capture.nil?

  env_truthy?(ENV["LOCAL_EMAIL_CAPTURE"]) || env_truthy?(ENV["AGENT_WORKTREE"])
end

.logo_for(title) ⇒ Object

Find a logo from theme_logos by title, with fallback chain:

  1. Exact title match

  2. “Navbar Logo” fallback

  3. First logo in the list



208
209
210
211
212
213
214
 
# File 'lib/studio.rb', line 208

def self.logo_for(title)
  logos = theme_logos.map { |l| l.is_a?(Hash) ? l : { file: l, title: l } }
  entry = logos.find { |l| l[:title] == title }
  entry ||= logos.find { |l| l[:title] == "Navbar Logo" }
  entry ||= logos.first
  entry ? "/#{entry[:file]}" : nil
end

.mailer_from_for_transport(env: ENV, ses_from:, resend_from: nil) ⇒ Object 



103
104
105
106
107
108
109
 
# File 'lib/studio.rb', line 103

def self.mailer_from_for_transport(env: ENV, ses_from:, resend_from: nil)
  if ses_transport_ready?(env)
    env_value(env, "MAILER_FROM") || ses_from
  else
    env_value(env, "RESEND_MAILER_FROM") || resend_from || resend_mailer_from
  end
end

.marketing_from_for_transport(env: ENV, ses_from:, resend_from: nil) ⇒ Object 



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/studio.rb', line 111

def self.marketing_from_for_transport(env: ENV, ses_from:, resend_from: nil)
  if ses_transport_ready?(env)
    env_value(env, "MARKETING_MAILER_FROM") || ses_from
  else
    env_value(env, "RESEND_MARKETING_FROM") ||
      env_value(env, "RESEND_MAILER_FROM") ||
      resend_from ||
      resend_mailer_from
  end
end

.routes(router) ⇒ Object 



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/studio.rb', line 220

def self.routes(router)
  router.instance_exec do
    get  "login",  to: "sessions#new"
    post "login",  to: "sessions#create"
    post "sso_continue", to: "sessions#sso_continue"
    get  "sso_login",    to: "sessions#sso_login"
    get  "logout", to: "sessions#destroy"
    get  "signup", to: "registrations#new"
    post "signup", to: "registrations#create"
    get  "auth/:provider/callback", to: "omniauth_callbacks#create"
    get  "auth/failure", to: "omniauth_callbacks#failure"

    unless defined?(Rails) && Rails.env.production?
      get "_studio/local_emails", to: "studio/local_emails#index", as: :studio_local_emails
    end

    # Passwordless email (magic link). Helpers: magic_link_request_path (POST
    # to request a link), magic_link_path(token) / magic_link_url(token:)
    # for the emailed GET confirmation page, and magic_link_consume_path(token)
    # for the scanner-safe POST consume. The token is a URL-safe
    # MessageVerifier blob but the constraint guards against a stray "."
    # segment.
    if Studio.draw_auth_routes && Studio.auth_method?(:magic_link)
      post "magic_link",        to: "magic_links#create",   as: :magic_link_request
      get  "magic_link/:token", to: "magic_links#confirm",  as: :magic_link,
           constraints: { token: %r{[^/]+} }
      post "magic_link/:token", to: "magic_links#consume",  as: :magic_link_consume,
           constraints: { token: %r{[^/]+} }
    end

    # Solana / Phantom wallet sign-in (nonce challenge + signature verify).
    # The browser posts to these literal paths from the shared Connect-Wallet
    # flow; app-specific surfaces (mobile deep-link callback, account-linking,
    # OAuth popup) stay in the consuming app's routes.
    if Studio.draw_auth_routes && Studio.auth_method?(:wallet)
      get  "auth/solana/nonce",  to: "solana_sessions#nonce",  as: :solana_nonce
      post "auth/solana/verify", to: "solana_sessions#verify", as: :solana_verify
    end

    resources :error_logs, only: [:index, :show]

    # Admin
    get   "admin/theme",            to: "theme_settings#edit",       as: :admin_theme
    patch "admin/theme",            to: "theme_settings#update",     as: :admin_theme_update
    post  "admin/theme/regenerate", to: "theme_settings#regenerate", as: :admin_theme_regenerate
    get   "admin/schema",           to: "schema#index",              as: :admin_schema
  end
end

.ses_transport_ready?(env = ENV) ⇒ Boolean

Returns:

  • (Boolean) 


122
123
124
125
126
 
# File 'lib/studio.rb', line 122

def self.ses_transport_ready?(env = ENV)
  env["MAIL_TRANSPORT"].to_s.downcase == "ses" &&
    env_value(env, "SES_SMTP_USERNAME") &&
    env_value(env, "SES_SMTP_PASSWORD")
end

.theme_config ⇒ Object 



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/studio.rb', line 192

def self.theme_config
  {
    primary: theme_primary,
    dark:    theme_dark,
    light:   theme_light,
    success: theme_success,
    warning: theme_warning,
    danger:  theme_danger,
    accent:  theme_accent
  }.compact
end

.user_wallet_address(user) ⇒ Object 



145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/studio.rb', line 145

def self.user_wallet_address(user)
  return nil unless user

  [wallet_address_method, :wallet_address, :solana_address].compact.each do |method|
    next unless user.respond_to?(method)

    value = user.public_send(method)
    return value if value && !(value.respond_to?(:empty?) && value.empty?)
  end

  nil
end

.validate_user_contract!(user_class) ⇒ Object

Verifies that the host app’s User model satisfies the engine’s expected contract. Raises Studio::UserContractError with a clear pointer to docs/USER_CONTRACT.md if anything required is missing. Called from Engine#after_initialize. Opt out via Studio.validate_user_contract = false.

Raises:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/studio.rb', line 162

def self.validate_user_contract!(user_class)
  return unless validate_user_contract
  return unless user_class.is_a?(Class)

  missing = []
  REQUIRED_USER_CLASS_METHODS.each do |m|
    missing << "User.#{m}" unless user_class.respond_to?(m)
  end
  instance_methods = REQUIRED_USER_INSTANCE_METHODS.dup
  instance_methods.concat(PASSWORD_USER_INSTANCE_METHODS) if auth_method?(:password)
  instance_methods.each do |m|
    missing << "User##{m}" unless user_class.instance_methods.include?(m)
  end

  return if missing.empty?

  raise UserContractError, <<~MSG
    The studio-engine gem's expected User model contract is not satisfied.

    Missing: #{missing.join(", ")}

    See the USER_CONTRACT.md doc in the studio-engine repo for the full
    contract + a minimal compliant example:
      https://github.com/amcritchie/studio-engine/blob/main/docs/USER_CONTRACT.md

    To bypass this check temporarily, set Studio.validate_user_contract = false
    in config/initializers/studio.rb.
  MSG
end