Release 202505311113

web/prisma/migrations/20250530205432_enable_pg_trgm_extension/migration.sql

@@ -0,0 +1,2 @@
+-- Enable pg_trgm extension for similarity functions
+CREATE EXTENSION IF NOT EXISTS pg_trgm;

web/src/actions/api/index.ts

@@ -0,0 +1,5 @@
+import { apiServiceActions } from './service'
+
+export const apiActions = {
+  service: apiServiceActions,
+}

web/src/actions/api/service.ts

@@ -0,0 +1,129 @@
+import { z } from 'astro/zod'
+import { ActionError } from 'astro:actions'
+import { pick } from 'lodash-es'
+
+import { getKycLevelInfo } from '../../constants/kycLevels'
+import { getVerificationStatusInfo } from '../../constants/verificationStatus'
+import { defineProtectedAction } from '../../lib/defineProtectedAction'
+import { prisma } from '../../lib/prisma'
+import { zodUrlOptionalProtocol } from '../../lib/zodUtils'
+
+import type { Prisma } from '@prisma/client'
+
+export const apiServiceActions = {
+  get: defineProtectedAction({
+    accept: 'json',
+    permissions: 'guest',
+    input: z.object({
+      id: z.coerce.number().int().positive().optional(),
+      slug: z
+        .string()
+        .min(1)
+        .max(2048)
+        .regex(/^[a-z0-9-]+$/, 'Allowed characters: lowercase letters, numbers, and hyphens')
+        .optional(),
+      url: zodUrlOptionalProtocol.optional(),
+    }),
+    handler: async (input) => {
+      if (!input.id && !input.slug && !input.url) {
+        throw new ActionError({
+          code: 'BAD_REQUEST',
+          message: 'At least one of the following parameters is required: id, slug, url',
+        })
+      }
+
+      const urlVariants = input.url
+        ? [input.url]
+            .flatMap((url) =>
+              [
+                url,
+                url.startsWith('http://') ? url.replace('http://', 'https://') : undefined,
+                url.startsWith('https://') ? url.replace('https://', 'http://') : undefined,
+              ].filter((url) => url !== undefined)
+            )
+            .flatMap((url) => [url, url.endsWith('/') ? url.slice(0, -1) : `${url}/`])
+        : undefined
+
+      const service = await prisma.service.findFirst({
+        where: {
+          listedAt: { lte: new Date() },
+          serviceVisibility: { in: ['PUBLIC', 'ARCHIVED', 'UNLISTED'] },
+
+          OR: [
+            ...(input.id ? ([{ id: input.id }] satisfies Prisma.ServiceWhereInput[]) : []),
+            ...(input.slug ? ([{ slug: input.slug }] satisfies Prisma.ServiceWhereInput[]) : []),
+            ...(urlVariants
+              ? ([
+                  { serviceUrls: { hasSome: urlVariants } },
+                  { onionUrls: { hasSome: urlVariants } },
+                  { i2pUrls: { hasSome: urlVariants } },
+                ] satisfies Prisma.ServiceWhereInput[])
+              : []),
+          ],
+        },
+        select: {
+          id: true,
+          name: true,
+          slug: true,
+          description: true,
+          kycLevel: true,
+          verificationStatus: true,
+          categories: {
+            select: {
+              name: true,
+              slug: true,
+            },
+          },
+          serviceUrls: true,
+          onionUrls: true,
+          i2pUrls: true,
+          tosUrls: true,
+          referral: true,
+          listedAt: true,
+          verifiedAt: true,
+          serviceVisibility: true,
+        },
+      })
+
+      if (
+        !service ||
+        (service.serviceVisibility !== 'PUBLIC' &&
+          service.serviceVisibility !== 'ARCHIVED' &&
+          service.serviceVisibility !== 'UNLISTED') ||
+        !service.listedAt ||
+        service.listedAt > new Date()
+      ) {
+        throw new ActionError({
+          code: 'NOT_FOUND',
+          message: 'Service not found',
+        })
+      }
+
+      return {
+        id: service.id,
+        slug: service.slug,
+        name: service.name,
+        description: service.description,
+        serviceVisibility: service.serviceVisibility,
+        verificationStatus: service.verificationStatus,
+        verificationStatusInfo: pick(getVerificationStatusInfo(service.verificationStatus), [
+          'value',
+          'slug',
+          'label',
+          'labelShort',
+          'description',
+        ]),
+        verifiedAt: service.verifiedAt,
+        kycLevel: service.kycLevel,
+        kycLevelInfo: pick(getKycLevelInfo(service.kycLevel.toString()), ['value', 'name', 'description']),
+        categories: service.categories,
+        listedAt: service.listedAt,
+        serviceUrls: [...service.serviceUrls, ...service.onionUrls, ...service.i2pUrls].map(
+          (url) => url + (service.referral ?? '')
+        ),
+        tosUrls: service.tosUrls,
+        kycnotmeUrl: `https://kycnot.me/service/${service.slug}`,
+      }
+    },
+  }),
+}

web/src/actions/index.ts

@@ -1,5 +1,6 @@
 import { accountActions } from './account'
 import { adminActions } from './admin'
+import { apiActions } from './api'
 import { commentActions } from './comment'
 import { notificationActions } from './notifications'
 import { serviceActions } from './service'
@@ -19,6 +20,7 @@ import { serviceSuggestionActions } from './serviceSuggestion'
 export const server = {
   account: accountActions,
   admin: adminActions,
+  api: apiActions,
   comment: commentActions,
   notification: notificationActions,
   service: serviceActions,

web/src/actions/serviceSuggestion.ts

@@ -1,10 +1,4 @@
-import {
+import { Currency } from '@prisma/client'
-  Currency,
-  ServiceSuggestionStatus,
-  ServiceSuggestionType,
-  ServiceVisibility,
-  VerificationStatus,
-} from '@prisma/client'
 import { z } from 'astro/zod'
 import { ActionError } from 'astro:actions'
 import { formatDistanceStrict } from 'date-fns'
@@ -12,6 +6,7 @@ import { formatDistanceStrict } from 'date-fns'
 import { captchaFormSchemaProperties, captchaFormSchemaSuperRefine } from '../lib/captchaValidation'
 import { defineProtectedAction } from '../lib/defineProtectedAction'
 import { saveFileLocally } from '../lib/fileStorage'
+import { findServicesBySimilarity } from '../lib/findServicesBySimilarity'
 import { handleHoneypotTrap } from '../lib/honeypot'
 import { prisma } from '../lib/prisma'
 import { separateServiceUrlsByType } from '../lib/urls'
@@ -29,11 +24,12 @@ export const SUGGESTION_DESCRIPTION_MAX_LENGTH = 100
 export const SUGGESTION_MESSAGE_CONTENT_MAX_LENGTH = 1000
 
 const findPossibleDuplicates = async (input: { name: string }) => {
-  const possibleDuplicates = await prisma.service.findMany({
+  const matches = await findServicesBySimilarity(input.name, 0.3)
+
+  return await prisma.service.findMany({
     where: {
-      name: {
+      id: {
-        contains: input.name,
+        in: matches.map(({ id }) => id),
-        mode: 'insensitive',
       },
     },
     select: {
@@ -43,8 +39,6 @@ const findPossibleDuplicates = async (input: { name: string }) => {
       description: true,
     },
   })
-
-  return possibleDuplicates
 }
 
 const serializeExtraNotes = <T extends Record<string, unknown>>(
@@ -118,9 +112,9 @@ export const serviceSuggestionActions = {
 
       const serviceSuggestion = await prisma.serviceSuggestion.create({
         data: {
-          type: ServiceSuggestionType.EDIT_SERVICE,
+          type: 'EDIT_SERVICE',
           notes: combinedNotes,
-          status: ServiceSuggestionStatus.PENDING,
+          status: 'PENDING',
           userId: context.locals.user.id,
           serviceId: service.id,
         },
@@ -229,12 +223,12 @@ export const serviceSuggestionActions = {
             kycLevel: input.kycLevel,
             acceptedCurrencies: input.acceptedCurrencies,
             imageUrl,
-            verificationStatus: VerificationStatus.COMMUNITY_CONTRIBUTED,
+            verificationStatus: 'COMMUNITY_CONTRIBUTED',
             overallScore: 0,
             privacyScore: 0,
             trustScore: 0,
             listedAt: new Date(),
-            serviceVisibility: ServiceVisibility.UNLISTED,
+            serviceVisibility: 'UNLISTED',
             categories: {
               connect: input.categories.map((id) => ({ id })),
             },
@@ -250,8 +244,8 @@ export const serviceSuggestionActions = {
         const serviceSuggestion = await tx.serviceSuggestion.create({
           data: {
             notes: input.notes,
-            type: ServiceSuggestionType.CREATE_SERVICE,
+            type: 'CREATE_SERVICE',
-            status: ServiceSuggestionStatus.PENDING,
+            status: 'PENDING',
             userId: context.locals.user.id,
             serviceId: service.id,
           },

web/src/components/Footer.astro

@@ -27,6 +27,12 @@ const links = [
     icon: 'i2p',
     external: true,
   },
+  {
+    href: '/docs/api',
+    label: 'API',
+    icon: 'ri:plug-line',
+    external: false,
+  },
   {
     href: '/about',
     label: 'About',

web/src/components/ServicesFilters.astro

@@ -49,6 +49,7 @@ const {
   class={cn(
     // Check the scam filter when there is a text quey and the user has checked verified and approved
     'has-[input[name=q]:not(:placeholder-shown)]:has-[&_input[name=verification][value=verified]:checked]:has-[&_input[name=verification][value=approved]:checked]:[&_input[name=verification][value=scam]]:checkbox-force-checked',
+    'has-[input[name=q]:placeholder-shown]:[&_[data-hide-if-q-is-empty]]:hidden has-[input[name=q]:not(:placeholder-shown)]:[&_[data-hide-if-q-is-filled]]:hidden',
     className
   )}
 >
@@ -80,16 +81,20 @@ const {
         ))
       }
     </select>
-    <p class="text-day-500 mt-1.5 text-center text-sm">
+    <p class="text-day-500 mt-1.5 text-center text-sm" data-hide-if-q-is-filled>
       <Icon name="ri:shuffle-line" class="inline-block size-3.5 align-[-0.125em]" />
       Ties randomly sorted
     </p>
+    <p class="text-day-500 mt-1.5 text-center text-sm" data-hide-if-q-is-empty>
+      <Icon name="ri:seo-line" class="inline-block size-3.5 align-[-0.125em]" />
+      Sorted by match first
+    </p>
   </fieldset>
 
   <!-- Text Search -->
   <fieldset class="mb-6">
     <legend class="font-title mb-3 leading-none text-green-500">
-      <label for="q">Text</label>
+      <label for="q">Name</label>
     </legend>
     <input
       type="text"

web/src/components/ServicesSearchResults.astro

@@ -71,7 +71,7 @@ const urlIfIncludingCommunity = urlWithParams(Astro.url, {
       />
 
       {
-        countCommunityOnly && (
+        !!countCommunityOnly && (
           <>
             <Button
               as="a"
@@ -192,7 +192,7 @@ const urlIfIncludingCommunity = urlWithParams(Astro.url, {
               inlineIcon={inlineIcons}
             />
           )}
-          {countCommunityOnly && (
+          {!!countCommunityOnly && (
             <Button
               as="a"
               href={urlIfIncludingCommunity}

web/src/constants/serviceVisibility.ts

@@ -65,7 +65,7 @@ export const {
       value: 'ARCHIVED',
       slug: 'archived',
       label: 'Archived',
-      description: 'No longer operational',
+      description: 'No longer operational.',
       longDescription:
         'Archived service, no longer exists or ceased operations. Information may be outdated.',
       icon: 'ri:archive-line',

web/src/lib/endpoints.ts

@@ -0,0 +1,32 @@
+import { type ActionClient } from 'astro:actions'
+
+import type { APIRoute } from 'astro'
+import type { z } from 'astro/zod'
+
+export function makeEndpointFromAction<Action extends ActionClient<unknown, 'json', z.ZodType> & string>(
+  action: Action
+): APIRoute {
+  return async (context) => {
+    try {
+      const input = await context.request.json()
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      const result = await context.callAction(action, input)
+
+      if (result.error) {
+        console.error('Error on endpoint', result.error)
+        return new Response(JSON.stringify({ error: result.error.message }), {
+          status: result.error.status,
+        })
+      }
+
+      return new Response(JSON.stringify(result.data), {
+        status: 200,
+      })
+    } catch (error) {
+      console.error('Error on endpoint', error)
+      return new Response(JSON.stringify({ error: 'Internal server error' }), {
+        status: 500,
+      })
+    }
+  }
+}

web/src/lib/errorBanners.ts

@@ -114,7 +114,13 @@ export class ErrorBanners {
       return result
     } catch (error) {
       this.handler(uiMessage)(error)
-      return fallback as F
+      return fallback as F extends never[]
+        ? T extends [infer _First, ...infer _Rest]
+          ? []
+          : T extends unknown[]
+            ? T[number][]
+            : F
+        : F
     }
   }
 

web/src/lib/findServicesBySimilarity.ts

@@ -0,0 +1,16 @@
+import { z } from 'astro/zod'
+
+import { prisma } from './prisma'
+
+export async function findServicesBySimilarity(value: string, similarityThreshold = 0.01) {
+  const data = await prisma.$queryRaw`
+      SELECT id, similarity(name, ${value}) AS similarity_score
+      FROM "Service"
+      WHERE similarity(name, ${value}) >= ${similarityThreshold}
+      ORDER BY similarity(name, ${value}) desc`
+
+  const schema = z.array(z.object({ id: z.number(), similarity_score: z.number() }))
+  const parsedData = schema.parse(data)
+
+  return parsedData.map(({ id, similarity_score }) => ({ id, similarityScore: similarity_score }))
+}

web/src/lib/makeAdminApiCallInfo.ts

@@ -0,0 +1,27 @@
+import type { Misc } from 'ts-toolbelt'
+
+export async function makeAdminApiCallInfo<T extends Misc.JSON.Object>({
+  method,
+  path,
+  input,
+  baseUrl,
+}: {
+  method: 'POST' | 'QUERY'
+  path: `/${string}`
+  input: T
+  baseUrl: URL | string
+}) {
+  const fullPath = new URL(`/api/v1${path}`, baseUrl).href
+
+  return {
+    method,
+    path,
+    fullPath,
+    input,
+    output: await fetch(fullPath, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input),
+    }).then((res) => res.json() as Promise<Misc.JSON.Value>),
+  }
+}

web/src/lib/prisma.ts

@@ -25,24 +25,23 @@ const findManyAndCount = {
   },
 }
 
-type FindManyAndCountType = typeof findManyAndCount.model.$allModels.findManyAndCount
+// NOTE: This used to be necessary to cast the prismaClientSingleton return type, but it seems not anymore. I left it, just in case we need it again
+// type FindManyAndCountType = typeof findManyAndCount.model.$allModels.findManyAndCount
 
-type ModelsWithCustomMethods = {
+// type ModelsWithCustomMethods = {
-  [Model in keyof PrismaClient]: PrismaClient[Model] extends {
+//   [Model in keyof PrismaClient]: PrismaClient[Model] extends {
-    findMany: (...args: any[]) => Promise<any>
+//     findMany: (...args: any[]) => Promise<any>
-  }
+//   }
-    ? PrismaClient[Model] & {
+//     ? PrismaClient[Model] & {
-        findManyAndCount: FindManyAndCountType
+//         findManyAndCount: FindManyAndCountType
-      }
+//       }
-    : PrismaClient[Model]
+//     : PrismaClient[Model]
-}
+// }
 
-type ExtendedPrismaClient = ModelsWithCustomMethods & PrismaClient
+// type ExtendedPrismaClient = ModelsWithCustomMethods & PrismaClient
 
-function prismaClientSingleton(): ExtendedPrismaClient {
+function prismaClientSingleton() {
-  const prisma = new PrismaClient().$extends(findManyAndCount)
+  return new PrismaClient().$extends(findManyAndCount)
-
-  return prisma as unknown as ExtendedPrismaClient
 }
 
 declare global {

web/src/pages/about.mdx

@@ -203,38 +203,9 @@ To **see comments waiting for moderation**, toggle the switch in the comments se
 
 ## API
 
-Access basic service data via our public API.
+You can access basic service data via our public API.
 
-**Attribution:** Please credit **KYCnot.me** if you use data from this API.
+See the [API page](/docs/api) for more details.
-
-### `GET /api/v1/service/[id]`
-
-Fetches details for a single service.
-
--   **`[id]`**: Can be a service ID, slug, name, or any registered URL (including .onion/.i2p).
-
-**Example Requests:**
-
-```
-/api/v1/service/bisq
-/api/v1/service/https://bisq.network
-```
-
-**Example Response (200 OK):**
-
-```json
-{
-  "name": "Bisq",
-  "description": "Decentralized Bitcoin exchange network.",
-  "kycLevel": 0,
-  "categories": ["exchange"],
-  "serviceUrls": ["https://bisq.network/"],
-  "onionUrls": [],
-  "i2pUrls": [],
-  "tosUrls": ["https://bisq.network/terms-of-service/"],
-  "kycnotmeUrl": "https://kycnot.me/service/bisq"
-}
-```
 
 ## Support
 

web/src/pages/account/edit.astro

@@ -53,7 +53,7 @@ const inputErrors = isInputError(result?.error) ? result.error.fields : {}
         disabled: !user.karmaUnlocks.displayName,
       }}
       description={!user.karmaUnlocks.displayName
-        ? `${makeKarmaUnlockMessage(karmaUnlocksById.displayName)} [Learn more](/karma)`
+        ? `${makeKarmaUnlockMessage(karmaUnlocksById.displayName)} [Learn more](/docs/karma)`
         : undefined}
     />
 
@@ -68,7 +68,7 @@ const inputErrors = isInputError(result?.error) ? result.error.fields : {}
         disabled: !user.karmaUnlocks.websiteLink,
       }}
       description={!user.karmaUnlocks.websiteLink
-        ? `${makeKarmaUnlockMessage(karmaUnlocksById.websiteLink)} [Learn more](/karma)`
+        ? `${makeKarmaUnlockMessage(karmaUnlocksById.websiteLink)} [Learn more](/docs/karma)`
         : undefined}
     />
 
@@ -80,7 +80,7 @@ const inputErrors = isInputError(result?.error) ? result.error.fields : {}
       square
       disabled={!user.karmaUnlocks.profilePicture}
       description={!user.karmaUnlocks.profilePicture
-        ? `${makeKarmaUnlockMessage(karmaUnlocksById.profilePicture)} [Learn more](/karma)`
+        ? `${makeKarmaUnlockMessage(karmaUnlocksById.profilePicture)} [Learn more](/docs/karma)`
         : undefined}
       removeCheckbox={user.picture
         ? {

web/src/pages/account/index.astro

@@ -529,8 +529,9 @@ if (!user) return Astro.rewrite('/404')
 
       <div class="border-night-500 bg-night-800/70 mb-4 rounded-md border px-4 py-3">
         <p class="text-day-300">
-          Earn karma to unlock features and privileges. <a href="/karma" class="text-day-200 hover:underline"
+          Earn karma to unlock features and privileges. <a
-            >Learn about karma</a
+            href="/docs/karma"
+            class="text-day-200 hover:underline">Learn about karma</a
           >
         </p>
       </div>

web/src/pages/admin/releases.astro

@@ -1,8 +1,8 @@
 ---
 import { RELEASE_DATE, RELEASE_NUMBER } from 'astro:env/server'
 
-import TimeFormatted from '../../components/TimeFormatted.astro'
 import MiniLayout from '../../layouts/MiniLayout.astro'
+import { timeAgo } from '../../lib/timeAgo'
 
 const releaseDate =
   RELEASE_DATE && !isNaN(new Date(RELEASE_DATE).getTime()) ? new Date(RELEASE_DATE) : undefined
@@ -37,7 +37,7 @@ const releaseDate =
   {
     !!releaseDate && (
       <p class="text-day-500 mt-2">
-        (<TimeFormatted date={releaseDate} hourPrecision daysUntilDate={Infinity} />)
+        (<time datetime={releaseDate.toISOString()}>{timeAgo.format(releaseDate, 'round')}</time>)
       </p>
     )
   }

web/src/pages/admin/services/[slug]/edit.astro

@@ -33,6 +33,7 @@ import {
   verificationStepStatuses,
 } from '../../../../constants/verificationStepStatus'
 import BaseLayout from '../../../../layouts/BaseLayout.astro'
+import { makeAdminApiCallInfo } from '../../../../lib/makeAdminApiCallInfo'
 import { pluralize } from '../../../../lib/pluralize'
 import { prisma } from '../../../../lib/prisma'
 
@@ -181,6 +182,20 @@ const [service, categories, attributes] = await Astro.locals.banners.tryMany([
 ])
 
 if (!service) return Astro.rewrite('/404')
+
+const apiCalls = await Astro.locals.banners.try(
+  'Error fetching api calls',
+  () =>
+    Promise.all([
+      makeAdminApiCallInfo({
+        method: 'QUERY',
+        path: '/service/get',
+        input: { slug: service.slug },
+        baseUrl: Astro.url,
+      }),
+    ]),
+  []
+)
 ---
 
 <BaseLayout pageTitle={`Edit Service: ${service.name}`}>
@@ -1100,5 +1115,25 @@ if (!service) return Astro.rewrite('/404')
         </form>
       </FormSubSection>
     </FormSection>
+
+    <FormSection title="API">
+      {
+        apiCalls.map((call) => (
+          <FormSubSection title={`${call.method} ${call.path}`}>
+            <p class="text-day-400 text-sm">Input:</p>
+            <pre
+              class="bg-night-800 border-night-500 text-day-300 overflow-x-auto rounded-md border p-3"
+              set:text={JSON.stringify(call.input, null, 2)}
+            />
+
+            <p class="text-day-400 text-sm">Output:</p>
+            <pre
+              class="bg-night-800 border-night-500 text-day-300 overflow-x-auto rounded-md border p-3"
+              set:text={JSON.stringify(call.output, null, 2)}
+            />
+          </FormSubSection>
+        ))
+      }
+    </FormSection>
   </div>
 </BaseLayout>

web/src/pages/api/[...catchAll].ts

@@ -0,0 +1,13 @@
+import type { APIRoute } from 'astro'
+
+export const ALL: APIRoute = (context) => {
+  console.error('Endpoint not found', { url: context.url.href, method: context.request.method })
+  return new Response(
+    JSON.stringify({
+      error: 'Endpoint not found',
+    }),
+    {
+      status: 404,
+    }
+  )
+}

web/src/pages/api/v1/service/[...id].ts

@@ -1,121 +0,0 @@
-import { prisma } from '../../../../lib/prisma'
-
-import type { Prisma } from '@prisma/client'
-import type { APIRoute } from 'astro'
-
-const MAX_ID_LENGTH = 2048
-
-export const GET: APIRoute = async ({ params }) => {
-  const { id } = params
-
-  if (!id) {
-    return new Response(JSON.stringify({ error: 'ID parameter is missing' }), {
-      status: 400,
-      headers: {
-        'Content-Type': 'application/json',
-      },
-    })
-  }
-
-  if (id.length > MAX_ID_LENGTH) {
-    return new Response(JSON.stringify({ error: 'ID parameter is too long' }), {
-      status: 400,
-      headers: {
-        'Content-Type': 'application/json',
-      },
-    })
-  }
-
-  const orConditions: Prisma.ServiceWhereInput[] = [
-    { slug: id },
-    { name: id },
-    { serviceUrls: { has: id } },
-    { onionUrls: { has: id } },
-    { i2pUrls: { has: id } },
-  ]
-
-  // Try direct ID lookup first
-  const numericId = parseInt(id, 10)
-
-  if (!isNaN(numericId)) {
-    orConditions.push({ id: numericId })
-  }
-
-  if (id.startsWith('http://') || id.startsWith('https://')) {
-    let alternativeId: string
-    if (id.endsWith('/')) {
-      alternativeId = id.slice(0, -1) // Remove trailing slash
-    } else {
-      alternativeId = id + '/' // Add trailing slash
-    }
-    orConditions.push({ serviceUrls: { has: alternativeId } })
-    orConditions.push({ onionUrls: { has: alternativeId } })
-    orConditions.push({ i2pUrls: { has: alternativeId } })
-  } else {
-    // For non-HTTP/S IDs, check as is (could be a direct onion/i2p address without protocol)
-    orConditions.push({ serviceUrls: { has: id } })
-    orConditions.push({ onionUrls: { has: id } })
-    orConditions.push({ i2pUrls: { has: id } })
-  }
-
-  try {
-    const service = await prisma.service.findFirst({
-      where: {
-        OR: orConditions,
-      },
-      select: {
-        name: true,
-        slug: true,
-        description: true,
-        kycLevel: true,
-        categories: {
-          select: {
-            name: true,
-            slug: true,
-            icon: true,
-          },
-        },
-        serviceUrls: true,
-        onionUrls: true,
-        i2pUrls: true,
-        tosUrls: true,
-      },
-    })
-
-    if (!service) {
-      return new Response(JSON.stringify({ error: 'Service not found' }), {
-        status: 404,
-        headers: {
-          'Content-Type': 'application/json',
-        },
-      })
-    }
-
-    const responseData = {
-      name: service.name,
-      description: service.description,
-      kycLevel: service.kycLevel,
-      categories: service.categories.map((category) => category.slug),
-      serviceUrls: service.serviceUrls,
-      onionUrls: service.onionUrls,
-      i2pUrls: service.i2pUrls,
-      tosUrls: service.tosUrls,
-      kycnotmeUrl: `https://kycnot.me/service/${service.slug}`,
-    }
-
-    return new Response(JSON.stringify(responseData), {
-      status: 200,
-      headers: {
-        'Content-Type': 'application/json',
-      },
-    })
-  } catch (error) {
-    console.error('Error fetching service:', error)
-    return new Response(JSON.stringify({ error: 'Internal server error' }), {
-      status: 500,
-      headers: {
-        'Content-Type': 'application/json',
-      },
-    })
-  }
-}

web/src/pages/api/v1/service/get.ts

@@ -0,0 +1,7 @@
+import { actions } from 'astro:actions'
+
+import { makeEndpointFromAction } from '../../../../lib/endpoints'
+
+import type { APIRoute } from 'astro'
+
+export const QUERY: APIRoute = makeEndpointFromAction(actions.api.service.get)

web/src/pages/docs/api.mdx

@@ -0,0 +1,174 @@
+---
+layout: ../../layouts/MarkdownLayout.astro
+title: API
+author: KYCnot.me
+pubDate: 2025-05-31
+description: 'Access basic service data via our public API.'
+icon: 'ri:plug-line'
+---
+
+import { SOURCE_CODE_URL } from 'astro:env/server'
+import { kycLevels } from '../../constants/kycLevels'
+import { verificationStatuses } from '../../constants/verificationStatus'
+import { serviceVisibilities } from '../../constants/serviceVisibility'
+
+Access basic service data via our public API.
+
+All endpoints should be prefixed with `/api/v1/`.
+
+The endpoints <a href={SOURCE_CODE_URL}>source code</a> is available on the `/web/src/actions/api/index.ts` file.
+
+**Attribution:** Please credit **KYCnot.me** if you use data from this API.
+
+## `QUERY` `/service/get`
+
+Fetches details for a single service by various lookup criteria.
+
+### Request Parameters
+
+| Parameter    | Type   | Required | Description |
+| ------------ | ------ | -------- | ----------- |
+| `id`         | number | No*       | Service ID |
+| `slug`       | string | No*       | Service URL slug (lowercase letters, numbers, and hyphens only) |
+| `serviceUrl` | string | No*       | Service URL. May be web, onion, or i2p. May just be a domain or a full URL. |
+
+\* At least one of the marked parameters is required.
+
+### Response Format
+
+```typescript
+type ServiceResponse = {
+  id: number
+  slug: string
+  name: string
+  description: string
+  serviceVisibility: 'PUBLIC' | 'ARCHIVED' | 'UNLISTED'
+  verificationStatus: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
+  verificationStatusInfo: {
+    value: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
+    slug: string
+    label: string
+    labelShort: string
+    description: string
+  }
+  verifiedAt: Date | null
+  kycLevel: 0 | 1 | 2 | 3 | 4
+  kycLevelInfo: {
+    value: 0 | 1 | 2 | 3 | 4
+    name: string
+    description: string
+  }
+  categories: {
+    name: string
+    slug: string
+  }[]
+  listedAt: Date
+  serviceUrls: string[]
+  tosUrls: string[]
+  kycnotmeUrl: `https://kycnot.me/service/${service.slug}`
+}
+```
+
+#### KYC Levels
+
+<ul>
+{kycLevels.map((level) => (
+  <li key={level.id}>
+    <strong>{level.id}</strong>: {level.name} - {level.description}
+  </li>
+))}
+</ul>
+
+#### Verification Status
+
+<ul>
+{verificationStatuses.map((status) => (
+  <li key={status.value}>
+    <strong>{status.value}</strong>: {status.description}
+  </li>
+))}
+</ul>
+
+#### Service Visibility
+
+<ul>
+{serviceVisibilities.filter((visibility) => visibility.value === 'PUBLIC' || visibility.value === 'ARCHIVED' || visibility.value === 'UNLISTED').map((visibility) => (
+  <li key={visibility.value}>
+    <strong>{visibility.value}</strong>: {visibility.longDescription}
+  </li>
+))}
+</ul>
+
+### Examples
+
+#### Request
+
+```zsh
+curl -X QUERY https://kycnot.me/api/v1/service/get \
+  -H "Content-Type: application/json" \
+  -d '{"slug": "my-example-service"}'
+```
+
+#### Response
+
+```json
+{
+  "name": "My Example Service",
+  "description": "This is a description of my example service",
+  "serviceVisibility": "PUBLIC",
+  "verificationStatus": "VERIFICATION_SUCCESS",
+  "verificationStatusInfo": {
+    "value": "VERIFICATION_SUCCESS",
+    "slug": "verified",
+    "label": "Verified",
+    "labelShort": "Verified",
+    "description": "Thoroughly tested and verified by the team. But things might change, this is not a guarantee."
+  },
+  "verifiedAt": "2025-01-20T07:12:29.393Z",
+  "kycLevel": 0,
+  "kycLevelInfo": {
+    "value": 0,
+    "name": "Guaranteed no KYC",
+    "description": "Terms explicitly state KYC will never be requested."
+  },
+  "categories": [
+    {
+      "name": "Exchange",
+      "slug": "exchange"
+    }
+  ],
+  "listedAt": "2025-05-31T19:09:18.043Z",
+  "serviceUrls": [
+    "https://example.com",
+    "http://c9ikae0fdidzh1ufrzp022e5uqfvz6ofxlkycz59cvo6fdxjgx7ekl9e.onion"
+  ],
+  "tosUrls": ["https://example.com/terms-of-service"],
+  "kycnotmeUrl": "https://kycnot.me/service/bisq"
+}
+```
+
+#### Error Responses
+
+**404 Not Found**: Service not found
+
+```json
+{
+  "error": "Service not found"
+}
+```
+
+**400 Bad Request**: Invalid input parameters
+
+```json
+{
+  "error": "Validation error message"
+}
+```
+
+**500 Internal Server Error**: Server error
+
+```json
+{
+  "error": "Internal server error"
+}
+```

web/src/pages/docs/karma.mdx

@@ -1,5 +1,5 @@
 ---
-layout: ../layouts/MarkdownLayout.astro
+layout: ../../layouts/MarkdownLayout.astro
 title: How does karma work?
 description: "KYCnot.me has a user karma system, here's how it works"
 icon: 'ri:hearts-line'
@@ -7,7 +7,7 @@ author: KYCnot.me
 pubDate: 2025-05-15
 ---
 
-import KarmaUnlocksTable from '../components/KarmaUnlocksTable.astro'
+import KarmaUnlocksTable from '../../components/KarmaUnlocksTable.astro'
 
 [KYCnot.me](https://kycnot.me) implements a karma system to encourage quality contributions and maintain community standards. Users can earn (or lose) karma points through various interactions on the platform, primarily through their comments on services.
 

web/src/pages/index.astro

@@ -26,6 +26,7 @@ import {
 } from '../constants/verificationStatus'
 import BaseLayout from '../layouts/BaseLayout.astro'
 import { areEqualArraysWithoutOrder, zodEnumFromConstant } from '../lib/arrays'
+import { findServicesBySimilarity } from '../lib/findServicesBySimilarity'
 import { parseIntWithFallback } from '../lib/numbers'
 import { areEqualObjectsWithoutOrder } from '../lib/objects'
 import { zodParseQueryParamsStoringErrors } from '../lib/parseUrlFilters'
@@ -213,17 +214,16 @@ const groupedAttributes = groupBy(
   'value'
 )
 
+const servicesQMatch = filters.q ? await findServicesBySimilarity(filters.q) : null
+
 const where = {
-  listedAt: {
+  id: servicesQMatch ? { in: servicesQMatch.map(({ id }) => id) } : undefined,
-    lte: new Date(),
+  listedAt: { lte: new Date() },
-  },
   categories: filters.categories.length ? { some: { slug: { in: filters.categories } } } : undefined,
   verificationStatus: {
     in: includeScams ? uniq([...filters.verification, 'VERIFICATION_FAILED'] as const) : filters.verification,
   },
-  serviceVisibility: {
+  serviceVisibility: { in: ['PUBLIC', 'ARCHIVED'] },
-    in: ['PUBLIC', 'ARCHIVED'],
-  },
   overallScore: { gte: filters['min-score'] },
   acceptedCurrencies: filters.currencies.length
     ? filters['currency-mode'] === 'and'
@@ -243,16 +243,6 @@ const where = {
           } satisfies Prisma.ServiceWhereInput,
         ]
       : []),
-    ...(filters.q
-      ? [
-          {
-            OR: [
-              { name: { contains: filters.q, mode: 'insensitive' as const } },
-              { description: { contains: filters.q, mode: 'insensitive' as const } },
-            ],
-          } satisfies Prisma.ServiceWhereInput,
-        ]
-      : []),
     ...(filters.networks.length
       ? [
           {
@@ -325,9 +315,8 @@ const [categories, [services, totalServices], countCommunityOnly, attributes] =
               select: {
                 services: {
                   where: {
-                    serviceVisibility: {
+                    serviceVisibility: { in: ['PUBLIC', 'ARCHIVED'] },
-                      in: ['PUBLIC', 'ARCHIVED'],
+                    listedAt: { lte: new Date() },
-                    },
                   },
                 },
               },
@@ -338,33 +327,45 @@ const [categories, [services, totalServices], countCommunityOnly, attributes] =
     [
       'Unable to load services.',
       async () => {
-        const [unsortedServices, totalServices] = await prisma.service.findManyAndCount({
+        const [unsortedServicesMissingSimilarityScore, totalServices] = await prisma.service.findManyAndCount(
-          where,
+          {
-          select: {
+            where,
-            id: true,
+            select: {
-            ...(Object.fromEntries(sortOptions.map((option) => [option.orderBy.key, true])) as Record<
+              id: true,
-              (typeof sortOptions)[number]['orderBy']['key'],
+              ...(Object.fromEntries(sortOptions.map((option) => [option.orderBy.key, true])) as Record<
-              true
+                (typeof sortOptions)[number]['orderBy']['key'],
-            >),
+                true
-          },
+              >),
-        })
+            },
+          }
+        )
+
+        const unsortedServices = unsortedServicesMissingSimilarityScore.map((service) => ({
+          ...service,
+          similarityScore: servicesQMatch?.find((match) => match.id === service.id)?.similarityScore ?? 0,
+        }))
 
         const rng = seedrandom(filters['sort-seed'])
         const selectedSort = sortOptions.find((sort) => sort.value === filters.sort) ?? defaultSortOption
 
         const sortedServices = orderBy(
           unsortedServices,
-          [selectedSort.orderBy.key, () => rng()],
+          [
-          [selectedSort.orderBy.direction, 'asc']
+            ...(filters.q ? (['similarityScore'] as const) : ([] as const)),
+            selectedSort.orderBy.key,
+            () => rng(),
+          ],
+          [...(filters.q ? (['desc'] as const) : ([] as const)), selectedSort.orderBy.direction, 'asc']
         ).slice((filters.page - 1) * PAGE_SIZE, filters.page * PAGE_SIZE)
 
-        const unsortedServicesWithInfo = await prisma.service.findMany({
+        const unsortedServicesWithInfoMissingSimilarityScore = await prisma.service.findMany({
           where: {
             id: {
               in: sortedServices.map((service) => service.id),
             },
           },
           select: {
+            id: true,
             name: true,
             slug: true,
             description: true,
@@ -398,14 +399,20 @@ const [categories, [services, totalServices], countCommunityOnly, attributes] =
           },
         })
 
+        const unsortedServicesWithInfo = unsortedServicesWithInfoMissingSimilarityScore.map((service) => ({
+          ...service,
+          similarityScore: servicesQMatch?.find((match) => match.id === service.id)?.similarityScore ?? 0,
+        }))
+
         const sortedServicesWithInfo = orderBy(
           unsortedServicesWithInfo,
           [
+            ...(filters.q ? (['similarityScore'] as const) : ([] as const)),
             selectedSort.orderBy.key,
             // Now we can shuffle indeternimistically, because the pagination was already applied
             () => Math.random(),
           ],
-          [selectedSort.orderBy.direction, 'asc']
+          [...(filters.q ? (['desc'] as const) : ([] as const)), selectedSort.orderBy.direction, 'asc']
         )
 
         return [sortedServicesWithInfo, totalServices] as const

web/src/pages/u/[username].astro

@@ -94,7 +94,16 @@ const user = await Astro.locals.banners.try('user', async () => {
               },
             },
           },
-          where: { service: { serviceVisibility: 'PUBLIC' } },
+          where: {
+            service: {
+              listedAt: {
+                lte: new Date(),
+              },
+              serviceVisibility: {
+                in: ['PUBLIC', 'ARCHIVED'],
+              },
+            },
+          },
           orderBy: { createdAt: 'desc' },
           take: 5,
         },
@@ -647,8 +656,9 @@ const isCurrentUser = !!Astro.locals.user && user.id === Astro.locals.user.id
 
       <div class="border-night-500 bg-night-800/70 mb-4 rounded-md border px-4 py-3">
         <p class="text-day-300">
-          Earn karma to unlock features and privileges. <a href="/karma" class="text-day-200 hover:underline"
+          Earn karma to unlock features and privileges. <a
-            >Learn about karma</a
+            href="/docs/karma"
+            class="text-day-200 hover:underline">Learn about karma</a
           >
         </p>
       </div>