iOS SDK

import VysloOpen

// appId comes from POST /open/apps — see the Quickstart.
let vyslo = VysloOpen(appId: 42)

// Optional base URL for a self-hosted or staging instance:
// VysloOpen(appId: 42, baseURL: URL(string: "https://your-instance/api/v1/app")!)

vyslo.isAuthorized     // Bool — is a token stored?
vyslo.token            // String? — the raw capability token

<!-- Open the VYSLO app for consent, and receive the callback -->
<key>LSApplicationQueriesSchemes</key>
<array><string>vyslo</string></array>
<key>CFBundleURLTypes</key>
<array><dict>
  <key>CFBundleURLSchemes</key><array><string>notesbot</string></array>
</dict></array>

<!-- Bluetooth to the card, and keep a connected card alive in the background -->
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Connect to your VYSLO card.</string>
<key>UIBackgroundModes</key>
<array><string>bluetooth-central</string></array>

<!-- Fast transfer over the card's Wi-Fi hotspot -->
<key>NSLocalNetworkUsageDescription</key>
<string>Copy recordings from your VYSLO card over its Wi-Fi.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Confirm that this iPhone joined the card's Wi-Fi.</string>

// 1. Send the user to the VYSLO app's consent screen.
let url = vyslo.authorizeURL(
    scopes: [.recordingsRead, .recordingsAudio],
    callbackURI: "notesbot://vyslo-auth"
)
UIApplication.shared.open(url) { opened in
    if !opened {
        // VYSLO app not installed — send them to install it.
    }
}

// 2. Handle the callback (SwiftUI shown; UIKit: scene(_:openURLContexts:)).
.onOpenURL { url in
    if vyslo.handleAuthorizationCallback(url) {
        // Token stored. Carry on.
    } else {
        // The user denied, or the callback carried no token.
    }
}

vyslo://open/authorize
    ?appId=<your app id>
    &scopes=<scope bitmap>
    &callback=<url-encoded callback uri>

# approved  ->  <callback>?vyslo_token=<capability token>
# denied    ->  <callback>?vyslo_error=denied

let rec: VysloRecording = try await vyslo.fetchRecording(recordingID)

rec.recordingID
rec.title
rec.segments               // [VysloRecording.Segment] (speaker, text, timestamp, identity)
rec.summaryLines           // [String]
rec.identity               // VysloIdentity for the recording as a whole
rec.ownerVerified          // shorthand: identity.verdict == .owner

// Needs .recordingsAudio in the grant.
let audio: Data = try await vyslo.fetchRecordingAudio(recordingID)

let id: VysloIdentity = rec.segments[0].identity

id.verdict                 // .owner, .likelyOwner or .other
id.source                  // .device, .hostedReview or .selfHosted
id.evidence                // .verified, .unverified or .unavailable
id.serverID                // which VYSLO server issued this result

// Needs .recordingsRead. Paged, newest first.
let page = try await vyslo.listRecordings(from: weekStart, to: .now, includesMe: true)
page.items                 // [VysloRecordingSummary]
page.nextCursor

// Needs .recordingsRead.
let hits = try await vyslo.searchTranscripts("budget", from: monthStart)

// Needs .insightsRead.
let week = try await vyslo.fetchWeeklyInsights()     // talk time, speaking share, topics, to-dos

// Needs .deviceStatusRead. Cloud snapshot, with observedAt.
let cards = try await vyslo.listDevices()

// Needs .transcriptionCreate. Any audio file, not only card recordings.
let job = try await vyslo.transcribe(fileURL, summarize: true)

let scan = vyslo.ble.startScan { card in
    card.name                 // the name the user gave the card in the VYSLO app
    card.identifier           // stable per iPhone
    card.rssi
}
// … once the user has picked a card
scan.stop()

let session: VysloCardSession = try await vyslo.ble.connect(card)

// Needs .deviceStatusRead.
let s = try await session.status()
s.batteryPercent
s.isCharging
s.storageUsedBytes
s.firmwareVersion
s.isRecording
s.isListening               // smart wake is listening, nothing is being stored
s.smartWakeEnabled

session.close()               // disconnects and releases the control lease if you hold it

// Needs .captureControl.
try await session.acquireControl()      // exclusive control lease; throws .leaseHeld if another app has it
try await session.startRecording()
try await session.pauseRecording()
try await session.resumeRecording()
try await session.stopRecording()
try await session.releaseControl()

// Needs .eventsSubscribe.
for await event in session.events {
    switch event {
    case .recordingStarted:              break
    case .recordingStopped(let id):      _ = id
    case .smartWakeTriggered:            break
    case .listeningChanged(let on):      _ = on
    case .buttonPressed:                 break
    case .chargingChanged(let charging): _ = charging
    }
}

// Needs .recordingsRead to list, .recordingsAudio to export.
let onCard: [VysloCardRecording] = try await session.listRecordings()
// id, startedAt, duration, sizeBytes

try await session.exportAudio(
    recordingID: onCard[0].id,
    format: .wav,                          // .opus, .wav or .pcm
    to: documents.appendingPathComponent("recording.wav")
) { progress in /* 0.0 – 1.0 */ }

// Needs .recordingsAudio. For many or long recordings.
try await session.fastTransfer(
    recordingIDs: onCard.map(\.id),
    format: .opus,
    to: documents.appendingPathComponent("vyslo")
) { done, total in }

// Needs .audioLive. Your app must be in the foreground.
let stream = try await session.startLiveAudio(format: .pcm) { frame in
    // 16 kHz mono frames while the user holds the card's button
}
stream.onPushToTalk = { pressed in }   // button down / up
stream.stop()

try await session.updateSettings(smartWakeEnabled: true)
try await session.updateSettings(name: "Work card")

let s = try await session.status()
s.smartWakeEnabled
s.isListening

// About 12 seconds of the user's own voice. Needs network.
for try await step in session.enrollVoiceprint() {
    switch step {
    case .recording(let level): showLevel(level)   // the user speaks now
    case .processing:           showProgress()
    case .done:                 showDone()
    }
}

if let update = try await session.checkFirmwareUpdate() {   // nil when up to date
    try await session.installFirmware(update, overWiFi: true) { progress in }
}

try await session.deleteRecording(recordingID)

// These wait for a press on the card, then run.
try await session.deleteAllRecordings()
try await session.resetVoiceprint()
try await session.unbind()

let caps = try await session.feedback.capabilities()   // states, events, modes, ranges, effect catalogue
let current = try await session.feedback.settings()    // your overrides, defaults, resolved values, revision

try await session.feedback.updateSettings(
    FeedbackPatch()
        .setLED("recording.smartWakeOn",
                .breathe(color: RGB(0, 60, 100), brightnessPercent: 40,
                         periodMs: 2400, minBrightnessPercent: 0))
        .setLED("idle.smartWakeOff", .off)
        .setHaptic("recording.started", .effect("START_CONFIRM"))
        .setHaptic("recording.stopped.SILENCE",
                   .pulses(levelPercent: 60, onMs: 80, offMs: 120, count: 2)),
    expectedRevision: current.revision          // rejected if another app saved in between
)

// Try before saving. A preview never saves and never fakes a real event.
let preview = try await session.feedback.previewLED(profile, durationMs: 3000)
try await session.feedback.stopPreview(preview.id)
try await session.feedback.previewHaptic(pattern)

try await session.feedback.restoreDefaults(["idle.smartWakeOff"])   // or restoreDefaults() for all
for await change in session.feedback.changes { }   // saved elsewhere, defaults restored, state changed
try await session.feedback.status()                // the state being shown right now, and why

// Call on foreground start. Internally rate-limited:
// does nothing if the stored token is younger than minAgeDays.
try await vyslo.renewIfNeeded()                 // default 7 days
try await vyslo.renewIfNeeded(minAgeDays: 3)

vyslo.setToken(token)                           // adopt a token you obtained yourself
vyslo.clearToken()                              // forget it (e.g. on your own sign-out)

do {
    let rec = try await vyslo.fetchRecording(recordingID)
} catch let error as VysloOpenError {
    switch error.statusCode {
    case 401, 403: reauthorize()     // token already cleared by the SDK
    case 404:      dropLocalCopy()   // hidden, deleted, or not this user's recording
    default:       retryLater(error.body)
    }
}

// Reference implementation — your server does the same thing in its own language.
let ok = VysloOpen.verifyWebhookSignature(
    webhookSecret: secret,
    rawBody: body,                         // exactly the bytes you received
    signature: request.value(forHTTPHeaderField: "X-Vyslo-Signature") ?? ""
)