@perryts/google-auth

Google Sign In bindings for Perry.

| Target | Implementation | | --------------- | ------------------------------------------------------------------------------------------------------- | | iOS 16+ | Native — Swift bridge over the GoogleSignIn SDK. | | macOS 13+ | Native — same Swift bridge. | | Android 7+ | Native — Kotlin bridge over androidx.credentials.CredentialManager with GetGoogleIdOption. | | Linux / Windows | Stub — every call resolves with {"success":false,"error":"unsupported-platform"}. | | tvOS / watchOS / visionOS | Stub — no first-party Google Sign In SDK on these platforms. |

Closes PerryTS/perry#1138 (follow-up to #674).

Installation

npm install @perryts/google-auth

The package targets perry-ffi ABI v0.5 (perry.nativeLibrary.abiVersion: "0.5" in package.json). Perry validates compatibility at build time.

Configuration

Add a [google_auth] block to your perry.toml:

[google_auth]
ios_client_id     = "1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"
android_client_id = "1234567890-zyxwvutsrqponmlkjihgfedcba.apps.googleusercontent.com"
server_client_id  = "1234567890-server.apps.googleusercontent.com"
default_scopes    = ["openid", "email", "profile"]

Perry's compile pipeline:

• iOS / macOS: writes GIDClientID, optional GIDServerClientID, and GIDDefaultScopes into the generated Info.plist, plus a CFBundleURLSchemes entry derived from the reversed client ID (required for the OAuth redirect).
• Android: writes the server client ID into res/values/strings.xml as google_auth_server_client_id. The Kotlin bridge reads it via R.string.google_auth_server_client_id and passes it to GetGoogleIdOption.Builder().setServerClientId(...). Perry merges the required gradle dependencies (androidx.credentials:credentials, androidx.credentials:credentials-play-services-auth, com.google.android.libraries.identity.googleid:googleid, kotlinx-coroutines-android) into the app's build.gradle.kts.

iOS / macOS GoogleSignIn SDK

The Swift bridge guards every SDK call with #if canImport(GoogleSignIn). Without the SDK on the swiftc framework search path, all three entry points resolve with {"success":false,"error":"framework-not-linked"}. To wire the real SDK:

1. Install the GoogleSignIn Swift package or CocoaPod.
2. Set PERRY_GOOGLE_SIGN_IN_FRAMEWORK_DIR=/path/to/Frameworks at build time, where /path/to/Frameworks contains GoogleSignIn.framework and its dependencies (GTMSessionFetcher, GoogleUtilities, AppAuth).
3. Perry forwards -F $PERRY_GOOGLE_SIGN_IN_FRAMEWORK_DIR to swiftc and adds -framework GoogleSignIn to the link line automatically.

Quick start

import {
  js_google_auth_sign_in,
  js_google_auth_silent_sign_in,
  js_google_auth_sign_out,
  type GoogleSignInResult,
} from "@perryts/google-auth";

// First-launch flow: try the silent path first; fall back to
// interactive on no-cached-session.
async function ensureSignedIn(): Promise<GoogleSignInResult> {
  const silent = JSON.parse(
    await js_google_auth_silent_sign_in(),
  ) as GoogleSignInResult;
  if (silent.success) return silent;

  if (silent.error === "no-cached-session") {
    return JSON.parse(await js_google_auth_sign_in()) as GoogleSignInResult;
  }
  // missing-client-id, framework-not-linked, jvm-unavailable, etc. —
  // surface upstream rather than re-prompting.
  return silent;
}

const result = await ensureSignedIn();
if (result.success) {
  // result.idToken → server-side verification
  // result.email, result.userId, result.name, result.pictureUrl → UI
} else if (result.cancelled) {
  // user dismissed the sheet
} else {
  console.error("sign-in failed:", result.error);
}

Error slugs

Every promise resolves; failures arrive via the { success: false, error } shape. Recognized slugs:

| Slug | Meaning | | --------------------------------- | ----------------------------------------------------------------------------- | | cancelled | User dismissed the system sign-in sheet (also sets cancelled: true). | | missing-client-id | [google_auth] ios_client_id / android_client_id not set in perry.toml. | | no-cached-session | Silent sign-in found no stored credentials. | | framework-not-linked | Apple build done without the GoogleSignIn SDK on the framework path. | | no-presenting-view-controller | iOS bridge couldn't locate the key window's root VC. | | no-presenting-window | macOS bridge couldn't locate keyWindow / mainWindow. | | no-user-returned | SDK returned without error but no GIDGoogleUser. | | sign-in-failed | Generic Apple SDK failure (network, server-config, etc.). | | android-credential-failed | Android CredentialManager surfaced a non-cancel error. | | unsupported-platform | Linux / Windows / tvOS / watchOS / visionOS stub. | | jvm-unavailable | Android JNI bridge couldn't reach the JavaVM (host-link misconfigured). | | not-installed | Android bridge missing application context (host didn't call install). | | null-result-from-bridge | Internal — Swift bridge returned a null pointer. | | non-utf8-result-from-bridge | Internal — bridge returned bytes that weren't valid UTF-8. |

Migration from the in-tree binding (perry < 0.5.1015)

Prior to v0.5.1015, @perryts/google-auth shipped inside the perry workspace as perry-ext-google-auth and was a not-yet-implemented stub. Replace the implicit binding with an explicit install:

npm install @perryts/google-auth

The import { js_google_auth_sign_in, ... } from "@perryts/google-auth" surface is unchanged.

License

MIT