trentlarson/crowd-funder-from-jason
1
0
Fork 0
forked from jsnbuchanan/crowd-funder-for-time-pwa
Code Issues Pull Requests Projects Releases Wiki Activity

refactor: reorganize deep linking types and interfaces

Browse Source 
Changes:
- Move deep link types from types/ to interfaces/
- Export baseUrlSchema for external use
- Add trailing commas for better git diffs
- Fix type inference for deepLinkSchemas
- Add deepLinks export to interfaces/index.ts
- Remove duplicate SuccessResult interface
- Update import paths in services/deepLinks.ts

This improves code organization by centralizing interface definitions
and fixing type inference issues.
This commit is contained in:
Matthew Raymer
2025-02-26 10:28:55 +00:00
parent 9d04db4a71
commit 20620c3aae
10 changed files with 1110 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
README.md
View File

@@ -8,8 +8,6 @@ and expand to crowd-fund with time & money, then record and see the impact of co
See [project.task.yaml](project.task.yaml) for current priorities.
(Numbers at the beginning of lines are estimated hours. See [taskyaml.org](https://taskyaml.org/) for details.)
## Setup & Building
Quick start:
@@ -19,15 +17,17 @@ npm install
npm run dev
```
See the test locations for "IMAGE_API_SERVER" or "PARTNER_API_SERVER" below, or use http://localhost:3000 for local endorser.ch
See the test locations for "IMAGE_API_SERVER" or "PARTNER_API_SERVER" below, or use <http://localhost:3000> for local endorser.ch
### Build the test & production app
```
```bash
npm run serve
```
### Lint and fix files
```
```bash
npm run lint
```
@@ -35,7 +35,6 @@ npm run lint
Look below for the "test-all" instructions.
### Compile and minify for test & production
* If there are DB changes: before updating the test server, open browser(s) with current version to test DB migrations.
@@ -52,11 +51,15 @@ Look below for the "test-all" instructions.
* For test, build the app (because test server is not yet set up to build):
```
```bash
TIME_SAFARI_APP_TITLE="TimeSafari_Test" VITE_APP_SERVER=https://test.timesafari.app VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch VITE_PASSKEYS_ENABLED=true npm run build
```
... and transfer to the test server: `rsync -azvu -e "ssh -i ~/.ssh/..." dist ubuntutest@test.timesafari.app:time-safari`
... and transfer to the test server:
```bash
rsync -azvu -e "ssh -i ~/.ssh/..." dist ubuntutest@test.timesafari.app:time-safari
```
(Let's replace that with a .env.development or .env.staging file.)
@@ -76,23 +79,14 @@ TIME_SAFARI_APP_TITLE="TimeSafari_Test" VITE_APP_SERVER=https://test.timesafari.
* Record the new hash in the changelog. Edit package.json to increment version & add "-beta", `npm install`, and commit. Also record what version is on production.
## Tests
See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
## Icons
To add an icon, add to main.ts and reference with `fa` element and `icon` attribute with the hyphenated name.
## Other
### Reference Material
@@ -104,7 +98,6 @@ To add an icon, add to main.ts and reference with `fa` element and `icon` attrib
* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",`
### Kudos
Gifts make the world go 'round!

915
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

2
package.json
View File

@@ -125,6 +125,8 @@
"eslint-plugin-prettier": "^5.2.1",
"eslint-plugin-vue": "^9.32.0",
"fs-extra": "^11.3.0",
"markdownlint": "^0.37.4",
"markdownlint-cli": "^0.44.0",
"npm-check-updates": "^17.1.13",
"postcss": "^8.4.38",
"prettier": "^3.2.5",

5
src/interfaces/common.ts
View File

@@ -19,11 +19,6 @@ export interface ResultWithType {
type: string;
}
export interface SuccessResult extends ResultWithType {
type: "success";
response: unknown;
}
export interface ErrorResponse {
error?: {
message?: string;

13
src/interfaces/deepLinks.ts Normal file
View File

@@ -0,0 +1,13 @@
/**
* @file Deep Link Interface Definitions
* @author Matthew Raymer
*
* Defines the core interfaces for the deep linking system.
* These interfaces are used across the deep linking implementation
* to ensure type safety and consistent error handling.
*/
export interface DeepLinkError extends Error {
code: string;
details?: unknown;
}

1
src/interfaces/index.ts
View File

@@ -4,3 +4,4 @@ export * from "./common";
export * from "./limits";
export * from "./records";
export * from "./user";
export * from "./deepLinks";

9
src/main.capacitor.ts
View File

@@ -72,9 +72,12 @@ const handleDeepLink = async (data: { url: string }) => {
await deepLinkHandler.handleDeepLink(data.url);
} catch (error) {
logConsoleAndDb("[DeepLink] Error handling deep link: " + error, true);
handleApiError({
message: error instanceof Error ? error.message : String(error)
} as AxiosError, "deep-link");
handleApiError(
{
message: error instanceof Error ? error.message : String(error),
} as AxiosError,
"deep-link",
);
}
};

83
src/services/deepLinks.ts
View File

@@ -29,13 +29,9 @@
*/
import { Router } from "vue-router";
import { deepLinkSchemas, DeepLinkParams } from "../types/deepLinks";
import { deepLinkSchemas, baseUrlSchema } from "../types/deepLinks";
import { logConsoleAndDb } from "../db";
interface DeepLinkError extends Error {
code: string;
details?: unknown;
}
import type { DeepLinkError } from "../interfaces/deepLinks";
export class DeepLinkHandler {
private router: Router;
@@ -44,6 +40,39 @@ export class DeepLinkHandler {
this.router = router;
}
/**
* Parses deep link URL into path, params and query components
*/
private parseDeepLink(url: string) {
const parts = url.split("://");
if (parts.length !== 2) {
throw { code: "INVALID_URL", message: "Invalid URL format" };
}
// Validate base URL structure
baseUrlSchema.parse({
scheme: parts[0],
path: parts[1],
queryParams: {}, // Will be populated below
});
const [path, queryString] = parts[1].split("?");
const [routePath, param] = path.split("/");
const query: Record<string, string> = {};
if (queryString) {
new URLSearchParams(queryString).forEach((value, key) => {
query[key] = value;
});
}
return {
path: routePath,
params: param ? { id: param } : {},
query,
};
}
/**
* Processes incoming deep links and routes them appropriately
* @param url The deep link URL to process
@@ -51,21 +80,23 @@ export class DeepLinkHandler {
async handleDeepLink(url: string): Promise<void> {
try {
logConsoleAndDb("[DeepLink] Processing URL: " + url, false);
const { path, params, query } = this.parseDeepLink(url);
await this.validateAndRoute(path, params, query);
// Ensure params is always a Record<string,string> by converting undefined to empty string
const sanitizedParams = Object.fromEntries(
Object.entries(params).map(([key, value]) => [key, value ?? ""]),
);
await this.validateAndRoute(path, sanitizedParams, query);
} catch (error) {
const deepLinkError = error as DeepLinkError;
logConsoleAndDb(
`[DeepLink] Error (${deepLinkError.code}): ${deepLinkError.message}`,
true
true,
);
throw {
code: deepLinkError.code || 'UNKNOWN_ERROR',
code: deepLinkError.code || "UNKNOWN_ERROR",
message: deepLinkError.message,
details: deepLinkError.details
details: deepLinkError.details,
};
}
}
@@ -76,25 +107,25 @@ export class DeepLinkHandler {
private async validateAndRoute(
path: string,
params: Record<string, string>,
query: Record<string, string>
query: Record<string, string>,
): Promise<void> {
const routeMap: Record<string, string> = {
claim: 'claim',
'claim-cert': 'claim-cert',
'claim-add-raw': 'claim-add-raw',
'contact-edit': 'contact-edit',
'contact-import': 'contact-import',
project: 'project',
'invite-one-accept': 'invite-one-accept',
'offer-details': 'offer-details',
'confirm-gift': 'confirm-gift'
claim: "claim",
"claim-cert": "claim-cert",
"claim-add-raw": "claim-add-raw",
"contact-edit": "contact-edit",
"contact-import": "contact-import",
project: "project",
"invite-one-accept": "invite-one-accept",
"offer-details": "offer-details",
"confirm-gift": "confirm-gift",
};
const routeName = routeMap[path];
if (!routeName) {
throw {
code: 'INVALID_ROUTE',
message: `Unsupported route: ${path}`
code: "INVALID_ROUTE",
message: `Unsupported route: ${path}`,
};
}
@@ -102,13 +133,13 @@ export class DeepLinkHandler {
const schema = deepLinkSchemas[path as keyof typeof deepLinkSchemas];
const validatedParams = await schema.parseAsync({
...params,
...query
...query,
});
await this.router.replace({
name: routeName,
params: validatedParams,
query
query,
});
}
}

20
src/types/deepLinks.ts
View File

@@ -28,46 +28,46 @@
import { z } from "zod";
// Base URL validation schema
const baseUrlSchema = z.object({
export const baseUrlSchema = z.object({
scheme: z.literal("timesafari"),
path: z.string(),
queryParams: z.record(z.string()).optional()
queryParams: z.record(z.string()).optional(),
});
// Parameter validation schemas for each route type
export const deepLinkSchemas = {
claim: z.object({
id: z.string().min(1),
view: z.enum(["details", "certificate", "raw"]).optional()
view: z.enum(["details", "certificate", "raw"]).optional(),
}),
contact: z.object({
did: z.string().regex(/^did:/),
action: z.enum(["edit", "import"]).optional(),
jwt: z.string().optional()
jwt: z.string().optional(),
}),
project: z.object({
id: z.string().min(1),
view: z.enum(["details", "edit"]).optional()
view: z.enum(["details", "edit"]).optional(),
}),
invite: z.object({
jwt: z.string().min(1),
type: z.enum(["one", "many"]).optional()
type: z.enum(["one", "many"]).optional(),
}),
gift: z.object({
id: z.string().min(1),
action: z.enum(["confirm", "details"]).optional()
action: z.enum(["confirm", "details"]).optional(),
}),
offer: z.object({
id: z.string().min(1),
view: z.enum(["details"]).optional()
})
view: z.enum(["details"]).optional(),
}),
};
export type DeepLinkParams = {
[K in keyof typeof deepLinkSchemas]: z.infer<typeof deepLinkSchemas[K]>;
[K in keyof typeof deepLinkSchemas]: z.infer<(typeof deepLinkSchemas)[K]>;
};

69
web-push.md
View File

@@ -37,7 +37,7 @@ possibility of users clicking "don't allow".
Now, to explain what happens in Typescript, we can activate a browser's
permission dialogue in this manner:
```
```typescript
function askPermission(): Promise<NotificationPermission> {
return new Promise(function(resolve, reject) {
const permissionResult = Notification.requestPermission(function(result) {
@@ -59,9 +59,9 @@ function askPermission(): Promise<NotificationPermission> {
The Notification.permission property indicates the permission level for the
current session and returns one of the following string values:
'granted': The user has granted permission for notifications.
'denied': The user has denied permission for notifications.
'default': The user has not made a choice yet.
- 'granted': The user has granted permission for notifications.
- 'denied': The user has denied permission for notifications.
- 'default': The user has not made a choice yet.
Once the user has granted permission, the client application registers a service
worker using the `ServiceWorkerRegistration` API.
@@ -77,7 +77,7 @@ subscriptions may be done.
Let's go through the `register` method first:
```
```javascript
navigator.serviceWorker.register('sw.js', { scope: '/' })
.then(function(registration) {
console.log('Service worker registered successfully:', registration);
@@ -108,7 +108,8 @@ Here's a version which can be used for testing locally. Note there can be
caching issues in your browser! Incognito is highly recommended.
sw-dev.ts
```
```typescript
self.addEventListener('push', function(event: PushEvent) {
console.log('Received a push message', event);
@@ -127,9 +128,9 @@ self.addEventListener('push', function(event: PushEvent) {
});
```
vue.config.js
```
```javascript
module.exports = {
pwa: {
workboxOptions: {
@@ -189,7 +190,7 @@ PROVIDER which creates and stores a special URL for that BROWSER.
Here's a bit of code describing the above process:
```
```typescript
// b64 is the VAPID
b64 = 'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U';
const applicationServerKey = urlBase64ToUint8Array(b64);
@@ -210,7 +211,7 @@ registration.pushManager.subscribe(options)
In this example, the `applicationServerKey` variable contains the VAPID public
key, which is converted to a `Uint8Array` using a function such as this:
```
```typescript
export function toUint8Array(base64String: string, atobFn: typeof atob): Uint8Array {
const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
@@ -242,6 +243,7 @@ The subscribe() method returns a `Promise` that resolves to a `PushSubscription`
object containing details of the subscription, such as the endpoint URL and the
public key. The returned data would have a form like this:
```json
{
"endpoint": "https://some.pushservice.com/some/unique/identifier",
"expirationTime": null,
@@ -250,6 +252,7 @@ public key. The returned data would have a form like this:
"auth": "some_other_base64_encoded_string"
}
}
```
endpoint: A string representing the endpoint URL for the push service. This
URL is essentially the push service address to which the push message would
@@ -273,7 +276,7 @@ via the PROVIDER so that they reach the BROWSER service worker.
Just to remind us that in our service worker our code for receiving messages
will look something like this:
```
```typescript
self.addEventListener('push', function(event: PushEvent) {
console.log('Received a push message', event);
@@ -292,7 +295,6 @@ self.addEventListener('push', function(event: PushEvent) {
});
```
Now to address the issue of receiving notification messages on mobile devices.
It should be noted that Web Push messages are only received when BROWSER is
open, except in the cases of Chrome and Firefox mobile BROWSERS. In iOS, the
@@ -300,13 +302,13 @@ mobile application (in our case a PWA) must be added to the Home Screen and
permissions must be explicitly granted that allow the application to receive
push notifications. Further, with an iOS device the user must enable wake on
notification to have their device light-up when it receives a notification
(https://support.apple.com/enus/HT208081).
(<https://support.apple.com/enus/HT208081>).
So what about #4? - The INTERMEDIARY. Well, It is possible under very special
circumstances to create your own Web Push PROVIDER. The only case I've found so
far relates to making an Android Custom ROM. (An Android Custom ROM is a
customized version of the Android Operating System.) There are open source
IMTERMEDIARY products such as UnifiedPush (https://unifiedpush.org/) which can
IMTERMEDIARY products such as UnifiedPush (<https://unifiedpush.org/>) which can
fulfill this role. If you are using iOS you are not permitted to make or use
your own custom Web Push PROVIDER. Apple will never allow anyone to do that.
Apple has none of its own.
@@ -315,8 +317,7 @@ It is, however, possible to have a sort of proxy working between your SERVICE
and FCM (or iOS). Services that mash up various Push notification services (like
OneSignal) can perform in the role of such proxies.
#4 -The INTERMEDIARY- doesn't appear to be anything we should be spending our
time on.
# 4 -The INTERMEDIARY- doesn't appear to be anything we should be spending our time on
A BROWSER may also remove a subscription. In order to remove a subscription,
the registration record must be retrieved from the serviceWorker using
@@ -326,8 +327,7 @@ subscription object, you may call the `unsubscribe` method. `unsubscribe` is
asynchronnous and returns a boolean true if it is successful in removing the
subscription and false if not.
```
```typescript
async function unsubscribeFromPush() {
// Check if the browser supports service workers
if ("serviceWorker" in navigator) {
@@ -362,30 +362,34 @@ unsubscribeFromPush().catch((err) => {
NOTE: We could offer an option within the app to "mute" these notifications. This wouldn't turn off the notifications at the browser level, but you could make it so that your Service Worker doesn't display them even if it receives them.
# NOTIFICATION DIALOG WORKFLOW
## ON APP FIRST-LAUNCH:
## ON APP FIRST-LAUNCH
The user is periodically presented with the notification permission dialog that asks them if they want to turn on notifications. User is given 3 choices:
- "Turn on Notifications": triggers the browser's own notification permission prompt.
- "Maybe Later": dismisses the dialog, to reappear at a later instance. (The next time the user launches the app? After X amount of days? A combination of both?)
- "Never": dismisses the dialog; app remembers to not automatically present the dialog again.
## IF THE USER CHOOSES "NEVER":
## IF THE USER CHOOSES "NEVER"
The dialog can still be accessed via the Notifications toggle switch in `AccountViewView` (which also tells the user if notifications are turned on or off).
## TO TEMPORARILY MUTE NOTIFICATIONS:
## TO TEMPORARILY MUTE NOTIFICATIONS
While notifications are turned on, the user can tap on the Mute Notifications toggle switch in `AccountViewView` (visible only when notifications are turned on) to trigger the Mute Notifications Dialog. User is given the following choices:
- Several "Mute for X Hour/s" buttons to temporarily mute notifications.
- "Mute until I turn it back on" button to indefinitely mute notifications.
- "Cancel" to make no changes and dismiss the dialog.
## TO UNMUTE NOTIFICATIONS:
## TO UNMUTE NOTIFICATIONS
Simply tap on the Mute Notifications toggle switch in `AccountViewView` to immediately unmute notifications. No dialog needed.
## TO TURN OFF NOTIFICATIONS:
## TO TURN OFF NOTIFICATIONS
While notifications are turned on, the user can tap on the App Notifications toggle switch in `AccountViewView` to trigger the Turn Off Notifications Dialog. User is given the following choices:
- "Turn off Notifications" to fully turn them off (which means the user will need to go through the dialogs agains to turn them back on).
@@ -393,29 +397,28 @@ While notifications are turned on, the user can tap on the App Notifications tog
# NOTIFICATION STATES
* Unpermissioned. Push server cannot send notifications to the user because it does not have permission.
- Unpermissioned. Push server cannot send notifications to the user because it does not have permission.
This may be the same as when the user gave permission in the past but has since revoked it at the OS or browser
level, outside the app. (User can change to Permissioned when the user gives permission.)
* Permissioned. (User can change to Unpermissioned via the OS or browser settings.)
* Active. (User can change to Muted when the user mutes notifications.)
* Muted. (User can change to Active when the user toggles it.)
- Permissioned. (User can change to Unpermissioned via the OS or browser settings.)
- Active. (User can change to Muted when the user mutes notifications.)
- Muted. (User can change to Active when the user toggles it.)
(Turning mute off automatically after some amount of time is not planned in version 1.)
# TROUBLESHOOTING
## Desktop
#### Firefox
### Firefox
Go to `about:debugging` and click on `Inspect` for the service worker.
#### Chrome
### Chrome
Go to `chrome://inspect/#service-workers` and click on `Inspect` for the service worker.
## Mobile
#### Android
### Android
#### iOS
### iOS