@proveanything/smartlinks 1.14.13 → 1.14.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/api/asset.js CHANGED
@@ -10,6 +10,7 @@ var __rest = (this && this.__rest) || function (s, e) {
10
10
  return t;
11
11
  };
12
12
  import { request, post, put, del, getApiHeaders, getBaseURL, isProxyEnabled, proxyUploadFormData } from "../http";
13
+ import { SmartlinksApiError } from "../types/error";
13
14
  export var asset;
14
15
  (function (asset) {
15
16
  function resolveApiUrl(path) {
@@ -175,7 +176,8 @@ export var asset;
175
176
  }
176
177
  catch (e) {
177
178
  const msg = (e === null || e === void 0 ? void 0 : e.message) || 'URL upload failed';
178
- throw new AssetUploadError(msg, 'UNKNOWN');
179
+ const details = e instanceof SmartlinksApiError ? e.errorResponse : undefined;
180
+ throw new AssetUploadError(msg, 'UNKNOWN', details);
179
181
  }
180
182
  }
181
183
  asset.uploadFromUrl = uploadFromUrl;
@@ -1,4 +1,4 @@
1
- import type { AuthLoginResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse } from "../types/authKit";
1
+ import type { AuthLoginResponse, AppleLoginOptions, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse } from "../types/authKit";
2
2
  /**
3
3
  * Namespace containing helper functions for the new AuthKit API.
4
4
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -17,6 +17,24 @@ export declare namespace authKit {
17
17
  function googleLogin(clientId: string, idToken: string): Promise<AuthLoginResponse>;
18
18
  /** Google OAuth login via server-side authorization code (public). */
19
19
  function googleCodeLogin(clientId: string, code: string, redirectUri: string): Promise<AuthLoginResponse>;
20
+ /**
21
+ * Sign in with Apple via an Apple identity token (public).
22
+ *
23
+ * Mirrors {@link googleLogin}. On success the returned bearer token is stored
24
+ * automatically and the cache is invalidated.
25
+ *
26
+ * Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`):
27
+ * - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400),
28
+ * `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500)
29
+ * - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this
30
+ * email; the server refuses to silently link. `err.details.requiresEmailVerification`
31
+ * is `true`. Recoverable: the user should sign in with their password (or reset it),
32
+ * then link Apple from settings. **The same 409 can now come back from
33
+ * {@link googleLogin}** under the shared verified-to-verified linking policy.
34
+ *
35
+ * @see AppleLoginOptions
36
+ */
37
+ function appleLogin(clientId: string, identityToken: string, opts?: AppleLoginOptions): Promise<AuthLoginResponse>;
20
38
  /** Send a magic link email to the user (public). */
21
39
  function sendMagicLink(clientId: string, data: {
22
40
  email: string;
@@ -43,6 +43,33 @@ export var authKit;
43
43
  return res;
44
44
  }
45
45
  authKit.googleCodeLogin = googleCodeLogin;
46
+ /**
47
+ * Sign in with Apple via an Apple identity token (public).
48
+ *
49
+ * Mirrors {@link googleLogin}. On success the returned bearer token is stored
50
+ * automatically and the cache is invalidated.
51
+ *
52
+ * Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`):
53
+ * - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400),
54
+ * `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500)
55
+ * - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this
56
+ * email; the server refuses to silently link. `err.details.requiresEmailVerification`
57
+ * is `true`. Recoverable: the user should sign in with their password (or reset it),
58
+ * then link Apple from settings. **The same 409 can now come back from
59
+ * {@link googleLogin}** under the shared verified-to-verified linking policy.
60
+ *
61
+ * @see AppleLoginOptions
62
+ */
63
+ async function appleLogin(clientId, identityToken, opts) {
64
+ const body = Object.assign({ identityToken }, opts);
65
+ const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/apple`, body);
66
+ if (res.token) {
67
+ setBearerToken(res.token);
68
+ invalidateCache();
69
+ }
70
+ return res;
71
+ }
72
+ authKit.appleLogin = appleLogin;
46
73
  /** Send a magic link email to the user (public). */
47
74
  async function sendMagicLink(clientId, data) {
48
75
  return post(`/authkit/${encodeURIComponent(clientId)}/auth/magic-link/send`, data);
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 1.14.13 | Generated: 2026-05-19T11:49:34.090Z
3
+ Version: 1.14.15 | Generated: 2026-05-31T15:31:06.561Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -2956,6 +2956,27 @@ interface AuthLoginResponse {
2956
2956
  requiresEmailVerification?: boolean // True if email verification is required but not yet completed
2957
2957
  emailVerificationDeadline?: number // Unix timestamp - for 'immediate' mode grace period deadline
2958
2958
  accountLocked?: boolean // True if account is locked due to expired verification deadline
2959
+ * True when this login created a brand-new account. Currently only populated by
2960
+ * the Apple login endpoint; left undefined by the other AuthKit login endpoints.
2961
+ isNewUser?: boolean
2962
+ * Session token expiry, in **milliseconds since epoch** (not seconds, not a duration),
2963
+ * or null when the server could not decode it. Currently only populated by the Apple
2964
+ * login endpoint.
2965
+ expiresAt?: number | null
2966
+ }
2967
+ ```
2968
+
2969
+ **AppleLoginOptions** (interface)
2970
+ ```typescript
2971
+ interface AppleLoginOptions {
2972
+ authorizationCode?: string
2973
+ * The **raw** nonce the client generated, if nonce binding was used. The server
2974
+ * accepts either `token.nonce === nonce` (native) or `token.nonce === sha256hex(nonce)` (web).
2975
+ nonce?: string
2976
+ * Name/email from Apple's **first** authorization callback only — Apple never returns
2977
+ * these again, and never inside the token. Forwarded so the server can persist the
2978
+ * display name on first account creation. Treated as untrusted (never used for identity).
2979
+ userInfo?: { email?: string; name?: string }
2959
2980
  }
2960
2981
  ```
2961
2982
 
@@ -3197,6 +3218,8 @@ interface AuthKitConfig {
3197
3218
  }
3198
3219
  ```
3199
3220
 
3221
+ **AuthKitErrorCode** = ``
3222
+
3200
3223
  **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
3201
3224
 
3202
3225
  ### batch
@@ -8271,6 +8294,9 @@ Google OAuth login via ID token (public).
8271
8294
  **googleCodeLogin**(clientId: string, code: string, redirectUri: string) → `Promise<AuthLoginResponse>`
8272
8295
  Google OAuth login via server-side authorization code (public).
8273
8296
 
8297
+ **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
8298
+ Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy.
8299
+
8274
8300
  **sendMagicLink**(clientId: string, data: { email: string; redirectUrl: string; accountData?: Record<string, any> }) → `Promise<MagicLinkSendResponse>`
8275
8301
  Send a magic link email to the user (public).
8276
8302
 
@@ -215,6 +215,49 @@ When `contactData.name` or explicit name parts were supplied on the original `se
215
215
  const session = await authKit.googleLogin(clientId, googleIdToken);
216
216
  ```
217
217
 
218
+ ### Sign in with Apple
219
+
220
+ Pass the Apple **identity token** (a JWT). On iOS/native it's
221
+ `ASAuthorizationAppleIDCredential.identityToken` (UTF-8 decoded); on web it's
222
+ `response.authorization.id_token` from Apple JS.
223
+
224
+ ```ts
225
+ const session = await authKit.appleLogin(clientId, appleIdentityToken, {
226
+ // All optional:
227
+ nonce, // raw nonce, if you used nonce binding
228
+ userInfo: { name, email }, // first authorization callback ONLY — Apple never resends it
229
+ });
230
+ // session.isNewUser and session.expiresAt (ms epoch) are populated by this endpoint.
231
+ ```
232
+
233
+ Apple returns the user's name/email **only on the very first authorization, ever**, and
234
+ never inside the token. Capture it from that first callback and forward it via `userInfo`
235
+ so the server can seed the display name — it's treated as untrusted and never used for identity.
236
+
237
+ Apple login requires the client's AuthKit config to list allowed audiences in
238
+ `appleClientIds`; until then the endpoint returns `400 APPLE_AUTH_NOT_CONFIGURED`.
239
+
240
+ #### Verified-to-verified account linking (affects Google too)
241
+
242
+ Both `appleLogin` and `googleLogin` now refuse to silently merge a federated login into a
243
+ pre-existing account whose email is **unverified**. Instead they throw
244
+ `SmartlinksApiError` with `errorCode === 'ACCOUNT_EXISTS_UNVERIFIED'` (409) and
245
+ `err.details?.requiresEmailVerification === true`. Treat this as recoverable, not fatal:
246
+
247
+ ```ts
248
+ try {
249
+ const session = await authKit.appleLogin(clientId, appleIdentityToken);
250
+ } catch (err) {
251
+ if (err instanceof SmartlinksApiError && err.errorCode === 'ACCOUNT_EXISTS_UNVERIFIED') {
252
+ // "An account with this email exists but isn't verified. Sign in with your
253
+ // password (or reset it), then link Apple/Google from settings."
254
+ }
255
+ }
256
+ ```
257
+
258
+ > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
259
+ > this case. Handle the 409 for both methods.
260
+
218
261
  ---
219
262
 
220
263
  ## Profile management
package/dist/http.js CHANGED
@@ -757,7 +757,7 @@ function ensureProxyListener() {
757
757
  const errorBody = (_d = (_c = msg.errorBody) !== null && _c !== void 0 ? _c : errObj) !== null && _d !== void 0 ? _d : msg.error;
758
758
  if (statusCode) {
759
759
  const errBody = normalizeErrorResponse(errorBody, statusCode);
760
- pending.reject(new SmartlinksApiError(message, statusCode, errBody));
760
+ pending.reject(new SmartlinksApiError(errBody.message, statusCode, errBody));
761
761
  }
762
762
  else {
763
763
  pending.reject(new Error(message));
@@ -431,7 +431,7 @@ export class IframeResponder {
431
431
  const fetchResponse = await fetch(fullUrl, fetchOptions);
432
432
  const responseData = await fetchResponse.json().catch(() => null);
433
433
  if (!fetchResponse.ok) {
434
- response.error = (responseData === null || responseData === void 0 ? void 0 : responseData.message) || `Request failed with status ${fetchResponse.status}`;
434
+ response.error = (responseData === null || responseData === void 0 ? void 0 : responseData.message) || (responseData === null || responseData === void 0 ? void 0 : responseData.errorText) || `Request failed with status ${fetchResponse.status}`;
435
435
  response.statusCode = fetchResponse.status;
436
436
  response.errorBody = responseData;
437
437
  }
package/dist/index.d.ts CHANGED
@@ -25,4 +25,4 @@ AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest,
25
25
  MobileAdminBundleManifest, } from './mobile-admin/types';
26
26
  export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
27
27
  export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';
28
- export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';
28
+ export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';
package/dist/openapi.yaml CHANGED
@@ -8177,6 +8177,38 @@ paths:
8177
8177
  description: Unauthorized
8178
8178
  404:
8179
8179
  description: Not found
8180
+ /authkit/{clientId}/auth/apple:
8181
+ post:
8182
+ tags:
8183
+ - authKit
8184
+ summary: Sign in with Apple via an Apple identity token (public).
8185
+ operationId: authKit_appleLogin
8186
+ security: []
8187
+ parameters:
8188
+ - name: clientId
8189
+ in: path
8190
+ required: true
8191
+ schema:
8192
+ type: string
8193
+ responses:
8194
+ 200:
8195
+ description: Success
8196
+ content:
8197
+ application/json:
8198
+ schema:
8199
+ $ref: "#/components/schemas/AuthLoginResponse"
8200
+ 400:
8201
+ description: Bad request
8202
+ 401:
8203
+ description: Unauthorized
8204
+ 404:
8205
+ description: Not found
8206
+ requestBody:
8207
+ required: true
8208
+ content:
8209
+ application/json:
8210
+ schema:
8211
+ $ref: "#/components/schemas/AppleLoginOptions"
8180
8212
  /authkit/{clientId}/auth/complete-reset:
8181
8213
  post:
8182
8214
  tags:
@@ -17929,8 +17961,22 @@ components:
17929
17961
  type: number
17930
17962
  accountLocked:
17931
17963
  type: boolean
17964
+ isNewUser:
17965
+ type: boolean
17966
+ expiresAt:
17967
+ type: number
17932
17968
  required:
17933
17969
  - user
17970
+ AppleLoginOptions:
17971
+ type: object
17972
+ properties:
17973
+ authorizationCode:
17974
+ type: string
17975
+ nonce:
17976
+ type: string
17977
+ userInfo:
17978
+ type: object
17979
+ additionalProperties: true
17934
17980
  MagicLinkSendResponse:
17935
17981
  type: object
17936
17982
  properties:
@@ -37,7 +37,47 @@ export interface AuthLoginResponse {
37
37
  requiresEmailVerification?: boolean;
38
38
  emailVerificationDeadline?: number;
39
39
  accountLocked?: boolean;
40
- }
40
+ /**
41
+ * True when this login created a brand-new account. Currently only populated by
42
+ * the Apple login endpoint; left undefined by the other AuthKit login endpoints.
43
+ */
44
+ isNewUser?: boolean;
45
+ /**
46
+ * Session token expiry, in **milliseconds since epoch** (not seconds, not a duration),
47
+ * or null when the server could not decode it. Currently only populated by the Apple
48
+ * login endpoint.
49
+ */
50
+ expiresAt?: number | null;
51
+ }
52
+ /**
53
+ * Options for {@link authKit.appleLogin}. All fields are optional — only the
54
+ * `identityToken` (passed as a positional argument) is required by the server.
55
+ */
56
+ export interface AppleLoginOptions {
57
+ /** Apple authorization code. Accepted but ignored by the server for now (reserved for future server-side token exchange). */
58
+ authorizationCode?: string;
59
+ /**
60
+ * The **raw** nonce the client generated, if nonce binding was used. The server
61
+ * accepts either `token.nonce === nonce` (native) or `token.nonce === sha256hex(nonce)` (web).
62
+ */
63
+ nonce?: string;
64
+ /**
65
+ * Name/email from Apple's **first** authorization callback only — Apple never returns
66
+ * these again, and never inside the token. Forwarded so the server can persist the
67
+ * display name on first account creation. Treated as untrusted (never used for identity).
68
+ */
69
+ userInfo?: {
70
+ email?: string;
71
+ name?: string;
72
+ };
73
+ }
74
+ /**
75
+ * Server-defined error codes returned by AuthKit federated-login endpoints
76
+ * (Apple + Google). Surfaced via `SmartlinksApiError.errorCode`. The
77
+ * `ACCOUNT_EXISTS_UNVERIFIED` case also carries `requiresEmailVerification: true`
78
+ * in `SmartlinksApiError.details`.
79
+ */
80
+ export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED';
41
81
  export interface MagicLinkSendResponse {
42
82
  success: boolean;
43
83
  message: string;
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 1.14.13 | Generated: 2026-05-19T11:49:34.090Z
3
+ Version: 1.14.15 | Generated: 2026-05-31T15:31:06.561Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -2956,6 +2956,27 @@ interface AuthLoginResponse {
2956
2956
  requiresEmailVerification?: boolean // True if email verification is required but not yet completed
2957
2957
  emailVerificationDeadline?: number // Unix timestamp - for 'immediate' mode grace period deadline
2958
2958
  accountLocked?: boolean // True if account is locked due to expired verification deadline
2959
+ * True when this login created a brand-new account. Currently only populated by
2960
+ * the Apple login endpoint; left undefined by the other AuthKit login endpoints.
2961
+ isNewUser?: boolean
2962
+ * Session token expiry, in **milliseconds since epoch** (not seconds, not a duration),
2963
+ * or null when the server could not decode it. Currently only populated by the Apple
2964
+ * login endpoint.
2965
+ expiresAt?: number | null
2966
+ }
2967
+ ```
2968
+
2969
+ **AppleLoginOptions** (interface)
2970
+ ```typescript
2971
+ interface AppleLoginOptions {
2972
+ authorizationCode?: string
2973
+ * The **raw** nonce the client generated, if nonce binding was used. The server
2974
+ * accepts either `token.nonce === nonce` (native) or `token.nonce === sha256hex(nonce)` (web).
2975
+ nonce?: string
2976
+ * Name/email from Apple's **first** authorization callback only — Apple never returns
2977
+ * these again, and never inside the token. Forwarded so the server can persist the
2978
+ * display name on first account creation. Treated as untrusted (never used for identity).
2979
+ userInfo?: { email?: string; name?: string }
2959
2980
  }
2960
2981
  ```
2961
2982
 
@@ -3197,6 +3218,8 @@ interface AuthKitConfig {
3197
3218
  }
3198
3219
  ```
3199
3220
 
3221
+ **AuthKitErrorCode** = ``
3222
+
3200
3223
  **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
3201
3224
 
3202
3225
  ### batch
@@ -8271,6 +8294,9 @@ Google OAuth login via ID token (public).
8271
8294
  **googleCodeLogin**(clientId: string, code: string, redirectUri: string) → `Promise<AuthLoginResponse>`
8272
8295
  Google OAuth login via server-side authorization code (public).
8273
8296
 
8297
+ **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
8298
+ Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy.
8299
+
8274
8300
  **sendMagicLink**(clientId: string, data: { email: string; redirectUrl: string; accountData?: Record<string, any> }) → `Promise<MagicLinkSendResponse>`
8275
8301
  Send a magic link email to the user (public).
8276
8302
 
package/docs/auth-kit.md CHANGED
@@ -215,6 +215,49 @@ When `contactData.name` or explicit name parts were supplied on the original `se
215
215
  const session = await authKit.googleLogin(clientId, googleIdToken);
216
216
  ```
217
217
 
218
+ ### Sign in with Apple
219
+
220
+ Pass the Apple **identity token** (a JWT). On iOS/native it's
221
+ `ASAuthorizationAppleIDCredential.identityToken` (UTF-8 decoded); on web it's
222
+ `response.authorization.id_token` from Apple JS.
223
+
224
+ ```ts
225
+ const session = await authKit.appleLogin(clientId, appleIdentityToken, {
226
+ // All optional:
227
+ nonce, // raw nonce, if you used nonce binding
228
+ userInfo: { name, email }, // first authorization callback ONLY — Apple never resends it
229
+ });
230
+ // session.isNewUser and session.expiresAt (ms epoch) are populated by this endpoint.
231
+ ```
232
+
233
+ Apple returns the user's name/email **only on the very first authorization, ever**, and
234
+ never inside the token. Capture it from that first callback and forward it via `userInfo`
235
+ so the server can seed the display name — it's treated as untrusted and never used for identity.
236
+
237
+ Apple login requires the client's AuthKit config to list allowed audiences in
238
+ `appleClientIds`; until then the endpoint returns `400 APPLE_AUTH_NOT_CONFIGURED`.
239
+
240
+ #### Verified-to-verified account linking (affects Google too)
241
+
242
+ Both `appleLogin` and `googleLogin` now refuse to silently merge a federated login into a
243
+ pre-existing account whose email is **unverified**. Instead they throw
244
+ `SmartlinksApiError` with `errorCode === 'ACCOUNT_EXISTS_UNVERIFIED'` (409) and
245
+ `err.details?.requiresEmailVerification === true`. Treat this as recoverable, not fatal:
246
+
247
+ ```ts
248
+ try {
249
+ const session = await authKit.appleLogin(clientId, appleIdentityToken);
250
+ } catch (err) {
251
+ if (err instanceof SmartlinksApiError && err.errorCode === 'ACCOUNT_EXISTS_UNVERIFIED') {
252
+ // "An account with this email exists but isn't verified. Sign in with your
253
+ // password (or reset it), then link Apple/Google from settings."
254
+ }
255
+ }
256
+ ```
257
+
258
+ > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
259
+ > this case. Handle the 409 for both methods.
260
+
218
261
  ---
219
262
 
220
263
  ## Profile management
package/openapi.yaml CHANGED
@@ -8177,6 +8177,38 @@ paths:
8177
8177
  description: Unauthorized
8178
8178
  404:
8179
8179
  description: Not found
8180
+ /authkit/{clientId}/auth/apple:
8181
+ post:
8182
+ tags:
8183
+ - authKit
8184
+ summary: Sign in with Apple via an Apple identity token (public).
8185
+ operationId: authKit_appleLogin
8186
+ security: []
8187
+ parameters:
8188
+ - name: clientId
8189
+ in: path
8190
+ required: true
8191
+ schema:
8192
+ type: string
8193
+ responses:
8194
+ 200:
8195
+ description: Success
8196
+ content:
8197
+ application/json:
8198
+ schema:
8199
+ $ref: "#/components/schemas/AuthLoginResponse"
8200
+ 400:
8201
+ description: Bad request
8202
+ 401:
8203
+ description: Unauthorized
8204
+ 404:
8205
+ description: Not found
8206
+ requestBody:
8207
+ required: true
8208
+ content:
8209
+ application/json:
8210
+ schema:
8211
+ $ref: "#/components/schemas/AppleLoginOptions"
8180
8212
  /authkit/{clientId}/auth/complete-reset:
8181
8213
  post:
8182
8214
  tags:
@@ -17929,8 +17961,22 @@ components:
17929
17961
  type: number
17930
17962
  accountLocked:
17931
17963
  type: boolean
17964
+ isNewUser:
17965
+ type: boolean
17966
+ expiresAt:
17967
+ type: number
17932
17968
  required:
17933
17969
  - user
17970
+ AppleLoginOptions:
17971
+ type: object
17972
+ properties:
17973
+ authorizationCode:
17974
+ type: string
17975
+ nonce:
17976
+ type: string
17977
+ userInfo:
17978
+ type: object
17979
+ additionalProperties: true
17934
17980
  MagicLinkSendResponse:
17935
17981
  type: object
17936
17982
  properties:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proveanything/smartlinks",
3
- "version": "1.14.13",
3
+ "version": "1.14.15",
4
4
  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",