@zwayam/apply-experience-library 0.1.2 → 0.1.4

package/README.md

@@ -1,94 +1,291 @@
-# Apply Experience Web SDK
+# Apply Experience Library
 
-Apply Experience is a reusable Add Profile widget for recruiter/admin web apps. It provides the popup UI for resume upload, candidate field capture, validations, phone fields, source/sub-source selection, and final profile submission flow.
+`@zwayam/apply-experience-library` is a host-facing SDK for launching **Add Profile** and **Edit Profile** popups inside recruiter or admin web applications.
 
-This repository root is installable directly from GitHub. The host app provides job/user context and API functions; the SDK handles the Add Profile experience.
+It is designed for hosts that already own authentication, API orchestration, and business rules, but want a reusable profile collection UI.
 
-## Install From GitHub
+## What the SDK Handles
 
-```bash
-npm install github:YOUR_GITHUB_USERNAME/YOUR_REPO_NAME#main
-```
+- resume upload and resume parsing flow
+- manual profile creation flow
+- add profile and edit profile popup UI
+- dynamic field rendering from backend `applyFields`
+- required validation, pattern validation, dependent field visibility
+- country code + phone input handling
+- source / source type / sub-source flow
+- optional location autosuggestions
+- final submit flow and success callbacks
+
+## What the Host App Handles
+
+- authentication and session
+- current job and user context
+- backend API calls
+- route-level state management
+- refresh / navigation after success
 
-Or install a tagged version:
+## Install
 
 ```bash
-npm install github:YOUR_GITHUB_USERNAME/YOUR_REPO_NAME#v0.2.1
+npm install @zwayam/apply-experience-library
 ```
 
-Import styles once:
+Import styles once in your host app:
 
-```js
+```ts
 import "@zwayam/apply-experience-library/styles.css";
 ```
 
-## Required Inputs
+## Exported API
 
-The host app must provide:
+The package exposes:
 
-- `container`: DOM element where the popup will mount.
-- `context`: current job, logged-in user, session, and optional environment data.
-- `api`: host-owned functions for loading config, parsing resume, submitting profile, and optional location suggestions.
+- `mountAddProfile(options)`
+- `mountEditProfile(options)`
+- `registerAddProfileElement(options)`
+- `registerEditProfileElement(options)`
 
-```js
-const context = {
+Use `mount*` for direct framework integration. Use `register*Element` if you prefer custom elements.
+
+## How It Is Built
+
+The SDK is made in two layers:
+
+1. `packages/react`
+   - React implementation of Add Profile / Edit Profile
+   - field rendering, validations, workflow logic
+
+2. `packages/web`
+   - bundled host-facing package
+   - exports mount helpers that work in Angular, React, Vue, and vanilla JS
+
+This means host apps do not need to know the internal React implementation details. They only provide `context`, `api`, and a DOM `container`.
+
+## Add Profile Context
+
+```ts
+type AddProfileHostContext = {
+  job: {
+    id: string;
+    companyId: number | string;
+    departmentId?: number | string;
+    jobTitle: string;
+    jobCode: string;
+    location?: string;
+    minYearOfExperience?: number;
+    maxYearOfExperience?: number;
+    departmentName?: string;
+  };
+  user: {
+    id: string | number;
+    email: string;
+    name: string;
+    uuid?: string;
+  };
+  session: {
+    sessionId: string;
+  };
+  environment?: Record<string, string>;
+};
+```
+
+### Example
+
+```ts
+const addProfileContext = {
   job: {
     id: "263294",
     companyId: 16136,
+    departmentId: 12,
     jobTitle: "Java Developer",
-    jobCode: "13949",
-    location: "Kolkata",
-    departmentName: "All Departments",
+    jobCode: "16667",
+    location: "Pune, Maharashtra, India",
+    minYearOfExperience: 2,
+    maxYearOfExperience: 5,
+    departmentName: "Engineering",
   },
   user: {
     id: 286813,
-    email: "user@example.com",
+    email: "recruiter@example.com",
     name: "Recruiter Name",
+    uuid: "host-user-uuid",
   },
   session: {
     sessionId: "SESSION_ID",
   },
+  environment: {
+    tenant: "prod",
+  },
 };
+```
 
-const api = {
-  loadInitialData: async () => ({
-    applyFields: [],
+## Edit Profile Context
+
+Edit Profile uses everything from Add Profile, plus:
+
+```ts
+type EditProfileHostContext = AddProfileHostContext & {
+  applyId: string | number;
+  application?: Record<string, unknown>;
+};
+```
+
+### Example
+
+```ts
+const editProfileContext = {
+  ...addProfileContext,
+  applyId: 987654,
+  application: {
+    applyId: 987654,
+    candidateId: 12345,
+  },
+};
+```
+
+## Add Profile API Contract
+
+```ts
+type AddProfileApi = {
+  loadInitialData(
+    context: AddProfileHostContext,
+  ): Promise<{
+    applyFields: AddProfileFieldDefinition[];
     supportedFiles: {
-      addProfile: {
-        fileFormat: ["pdf", "doc", "docx"],
-        fileSize: 3,
-      },
-    },
-    profileSources: [],
+      addProfile?: {
+        fileFormat: string[];
+        fileSize?: number;
+      };
+    };
+    profileSources: Array<{
+      sourceOfProfile?: string;
+      profileSource: string;
+      subSourceValues?: string | null;
+    }>;
     phoneConfiguration: {
-      countryIsoCode: "IN",
-      whatsAppEnabled: true,
-      maxCount: 3,
-    },
-  }),
+      countryIsoCode: string | null;
+      whatsAppEnabled: boolean;
+      maxCount: number;
+    };
+    resumeOptional?: boolean;
+  }>;
+
+  parseResume(
+    file: File,
+    context: AddProfileHostContext,
+  ): Promise<{
+    responseCode?: number;
+    reponseObject?: {
+      parsedObjectId?: string;
+      parsedResult?: {
+        profile?: Record<string, unknown>;
+      };
+      jobApplication?: Record<string, unknown>;
+    };
+  }>;
+
+  submitProfile(
+    payload: FormData,
+    context: AddProfileHostContext,
+  ): Promise<{
+    code?: number;
+    message?: string;
+    [key: string]: unknown;
+  }>;
+
+  getLocationSuggestions?(
+    query: string,
+    context: AddProfileHostContext,
+  ): Promise<string[]>;
+};
+```
 
-  parseResume: async (file) => {
-    const formData = new FormData();
-    formData.append("file", file);
-    return fetch("/parse-resume", { method: "POST", body: formData }).then((res) => res.json());
-  },
+## Edit Profile API Contract
 
-  submitProfile: async (payload) => {
-    return fetch("/add-profile", { method: "POST", body: payload }).then((res) => res.json());
-  },
+```ts
+type EditProfileApi = {
+  loadInitialData(
+    context: EditProfileHostContext,
+  ): Promise<{
+    jobApplication: Record<string, unknown>;
+    applyFieldsObject: Record<string, unknown>;
+    applyFields: AddProfileFieldDefinition[];
+    phoneConfiguration: {
+      countryIsoCode: string | null;
+      whatsAppEnabled: boolean;
+      maxCount: number;
+    };
+    phoneNumbers?: Array<Record<string, unknown>>;
+    supportedFiles?: {
+      addProfile?: {
+        fileFormat: string[];
+        fileSize?: number;
+      };
+    };
+  }>;
+
+  submitProfile(
+    payload: Record<string, unknown>,
+    context: EditProfileHostContext,
+  ): Promise<{
+    code?: number;
+    message?: string;
+    [key: string]: unknown;
+  }>;
+
+  getLocationSuggestions?(
+    query: string,
+    context: EditProfileHostContext,
+  ): Promise<string[]>;
 };
 ```
 
-## React
+## Field Definitions
+
+The SDK renders fields from backend `applyFields`.
+
+Common field types include:
+
+- `T` for text-like inputs
+- `D` for searchable dropdowns
+- `date`
+- `phone`
+- `checkbox`
+- `location`
+- `email`
+- `consent`
+
+Notes:
+
+- `field.errorMessage` is used as first priority for validation messages when present.
+- Generated SDK validation messages are used as fallback when API does not provide one.
+- Currency formatting follows field metadata type such as `INRCURRENCY` / `CURRENCY`, matching host behavior.
+
+## React Usage
 
-```jsx
+```tsx
 import { useEffect, useRef } from "react";
-import { mountAddProfile } from "@zwayam/apply-experience-library";
+import {
+  mountAddProfile,
+  type MountedAddProfile,
+  type AddProfileApi,
+  type AddProfileHostContext,
+} from "@zwayam/apply-experience-library";
 import "@zwayam/apply-experience-library/styles.css";
 
-export function AddProfile({ open, context, api, onClose }) {
-  const rootRef = useRef(null);
-  const mountedRef = useRef(null);
+export function AddProfileLauncher({
+  open,
+  context,
+  api,
+  onClose,
+}: {
+  open: boolean;
+  context: AddProfileHostContext;
+  api: AddProfileApi;
+  onClose(): void;
+}) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const mountedRef = useRef<MountedAddProfile | null>(null);
 
   useEffect(() => {
     if (!open || !rootRef.current) return;
@@ -97,8 +294,12 @@ export function AddProfile({ open, context, api, onClose }) {
       container: rootRef.current,
       context,
       api,
+      title: "Add Profile",
       onClose,
-      onSuccess: onClose,
+      onSuccess: () => {
+        mountedRef.current?.unmount();
+        onClose();
+      },
     });
 
     return () => mountedRef.current?.unmount();
@@ -108,55 +309,72 @@ export function AddProfile({ open, context, api, onClose }) {
 }
 ```
 
-## Angular
+## Angular Usage
 
-Import styles in a global stylesheet:
+Import styles once in a global stylesheet:
 
 ```scss
 @import "@zwayam/apply-experience-library/styles.css";
 ```
 
-Mount from a component:
+Mount from a component or service:
 
 ```ts
-import { mountAddProfile, MountedAddProfile } from "@zwayam/apply-experience-library";
+import {
+  mountAddProfile,
+  type MountedAddProfile,
+  type AddProfileApi,
+  type AddProfileHostContext,
+} from "@zwayam/apply-experience-library";
 
 private mountedAddProfile?: MountedAddProfile;
 
-openAddProfile(container: Element, context: any, api: any) {
+openAddProfile(container: Element, context: AddProfileHostContext, api: AddProfileApi) {
   this.mountedAddProfile = mountAddProfile({
     container,
     context,
     api,
+    title: "Add Profile",
     onClose: () => this.mountedAddProfile?.unmount(),
     onSuccess: () => {
       this.mountedAddProfile?.unmount();
-      // refresh host data if needed
+      // refresh host data here
     },
   });
 }
 ```
 
-## Vue
+## Vue Usage
 
 ```vue
-<script setup>
-import { onBeforeUnmount, onMounted, ref } from "vue";
+<script setup lang="ts">
+import { onBeforeUnmount, watch, ref } from "vue";
 import { mountAddProfile } from "@zwayam/apply-experience-library";
 import "@zwayam/apply-experience-library/styles.css";
 
-const root = ref(null);
-let mounted;
-
-onMounted(() => {
-  mounted = mountAddProfile({
-    container: root.value,
-    context,
-    api,
-    onClose: () => mounted?.unmount(),
-    onSuccess: () => mounted?.unmount(),
-  });
-});
+const props = defineProps<{
+  open: boolean;
+  context: any;
+  api: any;
+}>();
+
+const root = ref<HTMLElement | null>(null);
+let mounted: ReturnType<typeof mountAddProfile> | null = null;
+
+watch(
+  () => props.open,
+  (open) => {
+    if (!open || !root.value) return;
+
+    mounted = mountAddProfile({
+      container: root.value,
+      context: props.context,
+      api: props.api,
+      onClose: () => mounted?.unmount(),
+      onSuccess: () => mounted?.unmount(),
+    });
+  },
+);
 
 onBeforeUnmount(() => mounted?.unmount());
 </script>
@@ -166,7 +384,7 @@ onBeforeUnmount(() => mounted?.unmount());
 </template>
 ```
 
-## Vanilla JavaScript
+## Vanilla JavaScript Usage
 
 ```html
 <button id="open-add-profile">Add Profile</button>
@@ -177,28 +395,92 @@ onBeforeUnmount(() => mounted?.unmount());
 import { mountAddProfile } from "@zwayam/apply-experience-library";
 import "@zwayam/apply-experience-library/styles.css";
 
-document.querySelector("#open-add-profile").addEventListener("click", () => {
+document.getElementById("open-add-profile").addEventListener("click", () => {
   const mounted = mountAddProfile({
-    container: document.querySelector("#add-profile-root"),
-    context,
-    api,
+    container: document.getElementById("add-profile-root"),
+    context: addProfileContext,
+    api: addProfileApi,
     onClose: () => mounted.unmount(),
     onSuccess: () => mounted.unmount(),
   });
 });
 ```
 
+## Custom Element Usage
+
+```ts
+import {
+  registerAddProfileElement,
+  registerEditProfileElement,
+} from "@zwayam/apply-experience-library";
+
+registerAddProfileElement({
+  getApi: () => addProfileApi,
+  getContext: () => addProfileContext,
+});
+
+registerEditProfileElement({
+  getApi: () => editProfileApi,
+  getContext: () => editProfileContext,
+});
+```
+
+Then use:
+
+```html
+<apply-experience-add-profile></apply-experience-add-profile>
+<apply-experience-edit-profile></apply-experience-edit-profile>
+```
+
+## Example API Object
+
+```ts
+const addProfileApi = {
+  loadInitialData: async (context) => {
+    const response = await fetch(`/api/apply-fields?jobId=${context.job.id}`);
+    return response.json();
+  },
+
+  parseResume: async (file, context) => {
+    const formData = new FormData();
+    formData.append("file", file);
+    formData.append("sessionId", context.session.sessionId);
+    const response = await fetch("/api/parse-resume", {
+      method: "POST",
+      body: formData,
+    });
+    return response.json();
+  },
+
+  submitProfile: async (payload, context) => {
+    payload.append("sessionId", context.session.sessionId);
+    const response = await fetch("/api/add-profile", {
+      method: "POST",
+      body: payload,
+    });
+    return response.json();
+  },
+
+  getLocationSuggestions: async (query) => {
+    if (!query.trim()) return [];
+    const response = await fetch(`/api/location-suggestions?q=${encodeURIComponent(query)}`);
+    const data = await response.json();
+    return data.suggestions || [];
+  },
+};
+```
+
 ## Development
 
 ```bash
 npm install
 npm run build
+npm run playground
 ```
 
-The GitHub-installed package uses the built files from `packages/web/dist`, so keep `dist` committed when using GitHub installs.
-
-## Notes
+## Publish
 
-- The host app owns authentication, session handling, and API endpoints.
-- The SDK should be unmounted when the popup closes or the host component is destroyed.
-- The root package is configured for GitHub installation and exports the bundled web SDK.
+```bash
+npm run build
+npm publish --access public
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zwayam/apply-experience-library",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Host-facing Apply Experience SDK for Angular, React, Vue, and other frameworks.",
   "type": "module",
   "main": "./packages/web/dist/index.js",